1 · Dependencies & assets

TL;DR

Objective — get the frozen vendor snapshot ready to boot: authenticate Composer to dodge the rate limit, install PHP and JS dependencies without clobbering vendor patches, audit .env.example for fail-loud placeholders, then build and commit frontend assets.

User part + done-when

👤 User part — almost none: this step is entirely terminal-runnable. A person only needs to skim .env.example to confirm the loud placeholders match the project, and (optionally) restart their AI client after a Laravel Boost install.

Done when Composer is authenticated, composer install + npm install succeed, .env.example placeholders are loud, public/build/manifest.json is built and force-tracked, and an audit baseline is recorded.  ·  ⏱ ~20–40 min  ·  🤖 agent-runnable.

Background

The first boot starts with dependencies — but with three traps: Composer’s anonymous rate limit, the vendor’s patched vendor/ tree, and a .env.example full of real-looking placeholders that fail silently instead of loudly.

Steps

1. Authenticate Composer first

Give Composer a GitHub token before installing — anonymous pulls hit a 60-request/hour limit that fails large CodeCanyon installs partway through.

1. Hand Composer a GitHub token so it never hits the anonymous limit.

   composer config -g github-oauth.github.com "$(gh auth token)"
   # Expected: no output (the token is written to Composer's global auth.json)

   • ✅ The token is set without ever printing on screen.

2. Confirm it landed with an exit-code check — never by reading the file.

   composer config -g github-oauth.github.com >/dev/null 2>&1 && echo "✅ token set"
   # Expected: ✅ token set

   • ✅ ✅ token set prints.

The bare getter prints the token — and how to rotate it

composer config -g github-oauth.github.com with no value argument is a getter — it prints the raw token to stdout. Never let that output reach a terminal an AI agent is watching, or the token lands in the conversation log. Both commands above already discard stdout (gh auth token writes straight into Composer’s global auth.json; the verify step pipes to /dev/null and checks the exit code only). Don’t cat ~/.composer/auth.json, don’t paste the token into chat, and never paste it back “for verification”.

composer config --global github-oauth.github.com >/dev/null 2>&1 && echo "✅ token set"
# Expected: ✅ token set; no token characters printed

If the token leaked (you echoed it, pasted it, or it hit a log): rotate it.

gh auth refresh          # rotates your gh OAuth token, OR:
gh auth login --web      # fresh login
composer config -g github-oauth.github.com "$(gh auth token)" >/dev/null 2>&1
# Expected: no output; the new token overwrites the old one in Composer's global auth.json

2. Install PHP dependencies

Pull the locked PHP packages — but gate on vendor patches first if the ZIP shipped a pre-built vendor/.

1. If a shipped vendor/ exists, diff it before any install (skip if vendor/ came from a prior lock-file install).

   /tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/03-extract-and-snapshot/

   if [ -d vendor ] && [ -f composer.lock ]; then
     echo "Shipped vendor/ detected — run the P2 extract diff or P3 page-6 procedure before composer install"
     # or page 6: /tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/06-commit-and-secure/
   fi

   • ✅ Either no shipped vendor/ exists, or author patches are documented in _CUSTOMIZATIONS.md before the install below.

2. Install from the lock file.

   composer install
   # Expected: "Generating optimized autoload files" with no errors

   • ✅ vendor/ is populated and Composer exits cleanly.

3. If Composer dies with Allowed memory size … exhausted, lift the limit for the run.

   COMPOSER_MEMORY_LIMIT=-1 composer install
   # Expected: the install completes without the memory error

   • ✅ Install completes under the lifted memory limit (if needed).

4. Capture the required PHP extensions — the list the server must enable in Phase 4/9.

   composer check-platform-reqs 2>/dev/null | grep -E "^ext-" | awk '{print $1}' | sort
   # Expected: a sorted list of ext-* requirements — save it for server setup

   • ✅ The ext-* requirements are recorded for staging/production provisioning.

Identify vendor patches before any reinstall

CodeCanyon authors frequently patch code inside vendor/. A blind composer install over a shipped tree silently discards those patches. Step 1 above is mandatory when vendor/ came from the ZIP — the full comparison lives on Extract & snapshot (Phase 2) and Commit & secure (Phase 3).

Platform-drift trap — check server PHP before any later composer require

If your local PHP is higher than the server’s, a naive composer require <pkg> can pull transitives that need the higher PHP — producing a composer.lock that installs locally but aborts at deploy:vendors on the server with “your php version does not satisfy that requirement”.

LOCAL_PHP=$(php -r 'echo PHP_VERSION;')
SERVER_PHP=$(dep ssh staging "php -v | head -1" 2>/dev/null \
  | grep -oE 'PHP [0-9]+\.[0-9]+\.[0-9]+' | awk '{print $2}')
[ -z "$SERVER_PHP" ] && SERVER_PHP="(Phase 4 not done yet)"
echo "Local:  $LOCAL_PHP"
echo "Server: $SERVER_PHP"
if [ "$SERVER_PHP" != "(Phase 4 not done yet)" ]; then
  L=$(echo "$LOCAL_PHP" | grep -oE '^[0-9]+\.[0-9]+'); S=$(echo "$SERVER_PHP" | grep -oE '^[0-9]+\.[0-9]+')
  [ "$L" = "$S" ] && echo "✅ Local and server PHP match — plain composer require is safe" \
    || echo "⚠️  Drift: local $L ≠ server $S — pin the platform before composer require"
fi
# Expected: a match (safe) or a drift warning

Fix (preferred, version-controlled): pin the solver ceiling to the server’s PHP in composer.json — every developer who clones sees it, and it’s a solver ceiling only.

composer config platform.php x.y.z   # set to the REAL server PHP; log the value in _CUSTOMIZATIONS.md
grep -A3 '"config"' composer.json     # Expected: config.platform.php = "x.y.z"

Bump this value only after the server PHP is raised. Matching local PHP down to the server via Herd/Homebrew/Docker is also safe but heavier.

3. Audit .env.example for fail-loud placeholders

A .env.example that ships with plausible-but-fake values (APP_KEY=base64:abc…, DB_DATABASE=laravel) is dangerous: a teammate copies it, the app boots against the wrong database, and the failure surfaces hours later as corrupt data. Placeholders must fail loud — empty or obviously-fake — so a missing value crashes immediately.

1. Surface the risky keys.

   grep -E "^(APP_KEY|DB_DATABASE|DB_USERNAME|DB_PASSWORD|MAIL_|STRIPE_)" .env.example || true
   # Expected: a line per key — flag any with a real-looking value

   • ✅ The keys carrying plausible-but-fake values are visible.

2. Replace any real-looking value with a loud placeholder.

   Key	Loud placeholder
   APP_KEY=	leave blank — key:generate fills it
   DB_DATABASE=	"REPLACE_ME_DB_NAME"
   DB_USERNAME=	"REPLACE_ME_DB_USER"
   DB_PASSWORD=	"REPLACE_ME_DB_PASS"
   STRIPE_KEY= / STRIPE_SECRET=	leave blank

   • ✅ Every placeholder is blank or REPLACE_ME_* — nothing that could silently boot the wrong way.

Scan for hardcoded APP_ENV in vendor source

Some CodeCanyon vendors gate code paths on a specific APP_ENV value (for example APP_ENV=codecanyon). If you follow standard Laravel and set APP_ENV=staging, those paths silently break — admin-panel SMTP fields stop saving, payment-gateway config may not persist, and later phases debug the wrong layer. Scan now and record the result in _CUSTOMIZATIONS.md.

echo "=== APP_ENV hardcoding scan (vendor source) ==="
RESULTS=$(grep -rnE "env\('APP_ENV'\)\s*===?\s*['\"]|config\('app\.env'\)\s*===?\s*['\"]" \
  app/ Modules/ packages/ 2>/dev/null \
  | grep -viE "'(local|production|staging|testing)'" | head -20)
if [ -n "$RESULTS" ]; then
  echo "⚠️  Vendor hardcodes APP_ENV on a non-standard value — document in _CUSTOMIZATIONS.md:"
  echo "$RESULTS"
else
  echo "✅ No non-standard APP_ENV hardcoding found — vendor uses standard Laravel values"
fi
# Expected: the all-clear, or a file:line list of the hardcoded paths

Known vendor families:

Vendor family	Expected value	Affected code paths
Froiden line (SocietyPro, Worksuite, RentalPro, Housey, EduCenter, …)	APP_ENV=codecanyon	SMTP-details middleware gating admin-panel mail config
LiquidThemes (MagicAI + derivatives)	APP_ENV=codecanyon on older releases	Variable — check
InfyOm	Standard Laravel values	No known hardcoding

If your vendor is in this table, expect to configure SMTP and payment gateways via .env in Phase 6, not only through visible admin-panel fields.

Boost your AI workflow

Install Laravel Boost to register its MCP server in .mcp.json:

composer require laravel/boost --dev && php artisan boost:install

Record vendor gotchas (hardcoded APP_ENV, custom config providers, observer re-seed traps) in .claude/rules/project_context.md so every later AI session inherits them. Boost’s MCP tools stay inactive until you restart your AI client (👤).

4. Build & commit frontend assets

Frontend assets are built on your machine and committed, so the production server never needs Node.js (the build-locally strategy). Install JS deps, then build.

1. Install JS deps and build.

   npm install
   npm run build   # outputs to public/build/
   # Expected: a clean build with files written under public/build/

   • ✅ The build finishes and public/build/ is populated.

2. Force-track the build output — it’s often gitignored by default, but the server relies on it.

   git add -f public/build/
   ls public/build/manifest.json   # must exist
   # Expected: the manifest.json path prints

   • ✅ public/build/manifest.json exists and is staged in git.

Bundled node_modules / build can be poisoned

If the ZIP shipped a node_modules/ or public/build/ built for a different Node version or OS, npm run build may fail with platform/architecture errors. Fix by rebuilding clean: rm -rf node_modules && npm install && npm run build.

5. Run a security & dev-dependency audit

Capture a vulnerability baseline now — it’s the reference point for Phase 9 hardening. Don’t chase every advisory mid-setup; record the counts and move on unless something is critical in a runtime path.

1. Record the audit baseline.

   npm audit --omit=dev || true
   composer audit || true
   # Expected: advisory counts printed — note them, don't chase them all now

   • ✅ A baseline of npm + Composer advisories is recorded.

2. Confirm composer.json doesn’t autoload dev files in production — a "files" array under autoload-dev breaks the production boot (composer install --no-dev skips it). The full pre-deploy check lives on page 5.

   • ✅ No production-required file is hiding under autoload-dev.

Scan for dev-only packages used in production code paths

CodeCanyon apps often call dev-only packages (Faker, Debugbar, Telescope, Dusk, Mockery) from migrations, seeders, or service providers. These work locally but fail on deploy because composer install --no-dev drops them. Catch them now, not on first deploy.

echo "=== Dev dependencies in production code paths ==="
ISSUES=$(grep -rn "Faker\|Debugbar\|Telescope\|Dusk\|Mockery\|PHPUnit\|BrowserSync" \
  database/migrations/ database/seeders/ app/Providers/ app/Http/Middleware/ app/Http/Kernel.php \
  --include="*.php" 2>/dev/null \
  | grep -vE "class_exists|app\(\)->isLocal|app\(\)->environment\('local'\)|// ")
VENDOR_ISSUES=$(grep -rn "Faker\|Debugbar" \
  vendor/*/database/migrations/ packages/*/database/migrations/ \
  --include="*.php" 2>/dev/null | grep -vE "class_exists|// ")
[ -n "$ISSUES" ] && { echo "⚠️  In project files — wrap in class_exists() or guard with app()->isLocal():"; echo "$ISSUES" | head -10; }
[ -n "$VENDOR_ISSUES" ] && { echo "⚠️  In vendor/packages files — promote from require-dev to require (do NOT edit vendor):"; echo "$VENDOR_ISSUES" | head -10; }
[ -z "$ISSUES$VENDOR_ISSUES" ] && echo "✅ No dev dependencies found in production code paths"
# Expected: the all-clear, or a classified list of offending file:line entries

Location	Fix	Why
database/migrations/, database/seeders/	Wrap in if (class_exists(\Faker\Factory::class))	Project file — safe to edit
app/Providers/	Guard with if ($this->app->isLocal())	Project file — safe to edit
vendor/*/… or packages/*/…	Promote the package to require (composer require <pkg>)	Vendor file — never edit; updates overwrite it

A package the vendor calls in deploy-time migrations is effectively a production dependency regardless of being declared in require-dev.

6. Detect Stripe billing architecture

CodeCanyon Laravel apps ship wildly different Stripe wiring — canonical Laravel Cashier subscriptions, ad-hoc invoice-per-cycle code, or both architectures in the same codebase (a “dual-subsystem” pattern found in several Froiden/ResiDoro-family apps). Knowing which pattern is live gates every Stripe decision in Phase 6 (Task 62). Run the greps now, while vendor/ is fresh, and lock the answer into _CUSTOMIZATIONS.md.

Skip if no Stripe

If grep -r "Stripe" app/ config/ routes/ --include="*.php" -l returns nothing, the app has no Stripe integration — skip this step entirely and note no_stripe: true in _CUSTOMIZATIONS.md. You can also skip Phase 6 Task 62.

1. Check for canonical Laravel Cashier use (subscription model via the Billable trait).

   grep -rn "use.*Billable\|->newSubscription\|->subscriptions()\|Cashier::" \
     app/ --include="*.php" | head -20
   # Expected: lines containing Billable trait, newSubscription(), or Cashier:: facade — or no output

   • ✅ If output exists: canonical Cashier is present (at least partially). Note the files.
   • ✅ If no output: no Cashier subscriptions — the app uses ad-hoc invoices only.

2. Check for ad-hoc / custom Stripe webhook controller (invoice-per-cycle telltale).

   grep -rn "StripeWebhookController\|stripe.*invoice\|invoice.*stripe" \
     app/ --include="*.php" -i | head -20
   # Expected: custom webhook handler or invoice references — or no output

   • ✅ A custom StripeWebhookController confirms ad-hoc billing is present.

3. Check for dual-subsystem billing (SuperAdmin operator billing vs tenant-level billing — two separate Stripe flows).

   grep -rn "SuperAdmin\|superadmin\|super_admin" routes/ app/ \
     --include="*.php" | grep -i "stripe\|subscription\|billing" | head -20
   # Expected: SuperAdmin-namespaced billing routes signal the dual-subsystem pattern

   • ✅ If SuperAdmin-scoped Stripe routes appear alongside non-SuperAdmin Cashier use: dual-subsystem confirmed.

4. Record the findings in _CUSTOMIZATIONS.md.

   Use the decision table below to classify what you found, then replace the PROVISIONAL block (written in Phase 1B) with a VERIFIED block:

   What greps showed	Architecture	Stripe account strategy
   Cashier traits throughout, no custom webhook controller	Single-tenant Cashier	One Stripe account; restricted key rk_test_app_* safe
   Custom StripeWebhookController, no Cashier traits	Ad-hoc invoices only	Single Stripe account; standard key; webhook endpoint required
   Both Cashier traits AND custom controller	Dual-subsystem	Prefer a single Stripe account (Option C); both subsystems share one account
   SuperAdmin-scoped + non-SuperAdmin Cashier	Dual-subsystem (operator + tenant)	Prefer Option C; scope rk_test_app_* carefully
   No Stripe references found	No Stripe	Skip; note no_stripe: true

   # Run from the project root — updates _CUSTOMIZATIONS.md in-place
   import pathlib, datetime
   
   today = datetime.date.today().isoformat()
   f = pathlib.Path("_CUSTOMIZATIONS.md")
   if not f.exists():
       print("⚠️  _CUSTOMIZATIONS.md missing — create it first (Phase 1/2), then re-run.")
       raise SystemExit(1)
   text = f.read_text()
   
   old = "## Stripe account strategy — PROVISIONAL"
   new = f"## Stripe account strategy — VERIFIED {today}"
   if old in text:
       text = text.replace(old, new)
       # Append verification note after the header line
       note = (
           f"\n\n> **Verified {today}** via Phase-3 architecture detection greps.\n"
           "> Grep results: <!-- paste summary here -->\n"
           "> Architecture class: <!-- Cashier / Ad-hoc / Dual-subsystem / None -->\n"
       )
       text = text.replace(new, new + note, 1)
       f.write_text(text)
       print(f"✅ Updated: PROVISIONAL → VERIFIED {today}")
   else:
       print("⚠️  No PROVISIONAL block found — add the Stripe strategy block manually.")
   # Expected: "✅ Updated: PROVISIONAL → VERIFIED <date>"

   • ✅ _CUSTOMIZATIONS.md now has a VERIFIED Stripe strategy block with the grep summary and architecture class filled in.

Why this matters for Phase 6

Phase 6 Task 62 creates the actual Stripe restricted keys and configures the webhook endpoints. It must use the architecture class verified here — not the Phase 1B provisional guess. A wrong architecture class in Phase 6 means the webhook handler silently ignores events or processes them against the wrong subscription model.

Checklist

Do not mark this step done until every box below is checked.

• 🤖 Composer authenticated — no rate-limit failures.
• 🤖 Dependencies installed — composer install and npm install succeeded.
• 🤖 Vendor patches noted — any shipped-vendor/ patches flagged for the page-6 comparison.
• 🤖 Placeholders loud — .env.example values are blank or REPLACE_ME_*.
• 🤖 Build force-tracked — public/build/manifest.json built and git add -f’d.
• 🤖 Audit baseline recorded — npm audit / composer audit counts captured.
• 🤖 Stripe architecture verified — _CUSTOMIZATIONS.md updated with VERIFIED strategy, or skipped and no_stripe: true noted.

→Next step

Local database