@firenet-designs/fnd-cli 1.1.1 → 2.1.0

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @firenet-designs/fnd-cli
 $ fnd-cli COMMAND
 running command...
 $ fnd-cli (--version)
-@firenet-designs/fnd-cli/1.1.1 darwin-x64 node-v24.12.0
+@firenet-designs/fnd-cli/2.1.0 linux-x64 node-v24.12.0
 $ fnd-cli --help [COMMAND]
 USAGE
   $ fnd-cli COMMAND
@@ -29,8 +29,38 @@ USAGE
 <!-- usagestop -->
 # Commands
 <!-- commands -->
+* [`fnd-cli backfill-project [SHOP]`](#fnd-cli-backfill-project-shop)
 * [`fnd-cli create-app`](#fnd-cli-create-app)
+* [`fnd-cli create-project [SHOP]`](#fnd-cli-create-project-shop)
 * [`fnd-cli help [COMMAND]`](#fnd-cli-help-command)
+* [`fnd-cli token`](#fnd-cli-token)
+
+## `fnd-cli backfill-project [SHOP]`
+
+Backfill missing scaffold files in an EXISTING repo + theme: .gitignore, .shopifyignore, CLAUDE.md. Each is created only if absent — existing files are left untouched. Does NOT git init, pull the theme, commit, or touch GitHub.
+
+```
+USAGE
+  $ fnd-cli backfill-project [SHOP...]
+
+ARGUMENTS
+  [SHOP...]  Shopify store handle, passed to Claude as a hint
+
+DESCRIPTION
+  Backfill missing scaffold files in an EXISTING repo + theme: .gitignore, .shopifyignore, CLAUDE.md. Each is created
+  only if absent — existing files are left untouched. Does NOT git init, pull the theme, commit, or touch GitHub.
+
+  Requires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.
+
+EXAMPLES
+  $ fnd-cli backfill-project
+
+  $ fnd-cli backfill-project my-store
+
+  $ fnd-cli backfill-project my-store "extra hints"
+```
+
+_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.1.0/src/commands/backfill-project.ts)_
 
 ## `fnd-cli create-app`
 
@@ -51,7 +81,37 @@ EXAMPLES
   $ fnd-cli create-app
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v1.1.1/src/commands/create-app.ts)_
+_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.1.0/src/commands/create-app.ts)_
+
+## `fnd-cli create-project [SHOP]`
+
+Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.
+
+```
+USAGE
+  $ fnd-cli create-project [SHOP...]
+
+ARGUMENTS
+  [SHOP...]  Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)
+
+DESCRIPTION
+  Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated
+  CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.
+
+  Requires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.
+
+  GitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI
+  never stores credentials. Override the org with FND_GH_ORG.
+
+EXAMPLES
+  $ fnd-cli create-project
+
+  $ fnd-cli create-project my-store
+
+  $ fnd-cli create-project my-store "Acme storefront, Klaviyo"
+```
+
+_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.1.0/src/commands/create-project.ts)_
 
 ## `fnd-cli help [COMMAND]`
 
@@ -72,4 +132,36 @@ DESCRIPTION
 ```
 
 _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.37/src/commands/help.ts)_
+
+## `fnd-cli token`
+
+Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works cross-org, unlike client_credentials.
+
+```
+USAGE
+  $ fnd-cli token [-i <value>] [-c <value>] [--no-open] [-p <value>] [--scopes <value>] [-s <value>] [-w
+    <value>]
+
+FLAGS
+  -c, --client-secret=<value>  app Client secret (shpss_...)
+  -i, --client-id=<value>      app Client ID
+  -p, --port=<value>           [default: 3456] local callback port (must match the app redirect URL)
+  -s, --store=<value>          store domain (mystore or mystore.myshopify.com)
+  -w, --write=<value>          path to an .mcp.json whose 'shopify' server should be rewritten to use the token
+      --no-open                don't auto-open the authorize URL in a browser
+      --scopes=<value>         [default: read_products] comma-separated Admin API scopes to request
+
+DESCRIPTION
+  Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works
+  cross-org, unlike client_credentials.
+
+EXAMPLES
+  $ fnd-cli token --store trafalgar-store --client-id 0b42... --client-secret shpss_...
+
+  $ fnd-cli token -s mystore -i <id> -c <secret> --scopes read_products,read_orders
+
+  $ fnd-cli token -s mystore -i <id> -c <secret> --write ./.mcp.json
+```
+
+_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.1.0/src/commands/token.ts)_
 <!-- commandsstop -->

package/dist/commands/backfill-project.d.ts

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+export default class BackfillProject extends Command {
+    static args: {
+        shop: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/backfill-project.js

@@ -0,0 +1,61 @@
+import { Args, Command } from '@oclif/core';
+import chalk from 'chalk';
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, SHOPIFYIGNORE_CONTENT, } from '../lib/scaffold.js';
+export default class BackfillProject extends Command {
+    static args = {
+        shop: Args.string({ description: 'Shopify store handle, passed to Claude as a hint', required: false }),
+    };
+    static description = 'Backfill missing scaffold files in an EXISTING repo + theme: .gitignore, .shopifyignore, CLAUDE.md. Each is created only if absent — existing files are left untouched. Does NOT git init, pull the theme, commit, or touch GitHub.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> my-store',
+        '<%= config.bin %> <%= command.id %> my-store "extra hints"',
+    ];
+    // Everything after the shop handle is collected as free-form hints for Claude.
+    static strict = false;
+    async run() {
+        const { argv } = await this.parse(BackfillProject);
+        const [shop, ...rest] = argv;
+        const hints = rest.join(' ');
+        if (existsSync('.gitignore')) {
+            this.log(chalk.dim('✓ .gitignore exists — skipping'));
+        }
+        else {
+            writeFileSync('.gitignore', GITIGNORE_CONTENT);
+            this.log(chalk.green('✅ .gitignore created'));
+        }
+        if (existsSync('.shopifyignore')) {
+            this.log(chalk.dim('✓ .shopifyignore exists — skipping'));
+        }
+        else {
+            writeFileSync('.shopifyignore', SHOPIFYIGNORE_CONTENT);
+            this.log(chalk.green('✅ .shopifyignore created'));
+        }
+        if (existsSync(join(process.cwd(), 'CLAUDE.md'))) {
+            this.log(chalk.dim('✓ CLAUDE.md exists — skipping'));
+            return;
+        }
+        this.log(chalk.blue('🤖 Generating CLAUDE.md with Claude…'));
+        const result = await generateClaudeMd(shop, hints);
+        switch (result) {
+            case 'claude-not-installed': {
+                this.error('claude CLI not found — install it with: npm install -g @anthropic-ai/claude-code', { code: '1' });
+                break;
+            }
+            case 'missing-prompt': {
+                this.error(`bundled prompt missing at ${initPromptPath()} — try reinstalling @firenet-designs/fnd-cli`, { code: '1' });
+                break;
+            }
+            case 'not-written': {
+                this.warn('Claude finished but no CLAUDE.md was found — check the output above');
+                break;
+            }
+            case 'written': {
+                this.log(chalk.green(`✅ CLAUDE.md written to ${process.cwd()}`));
+                break;
+            }
+        }
+    }
+}

package/dist/commands/create-project.d.ts

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+export default class CreateProject extends Command {
+    static args: {
+        shop: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/create-project.js

@@ -0,0 +1,122 @@
+import { Args, Command } from '@oclif/core';
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { simpleGit } from 'simple-git';
+import { findShopifyBin, generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, run, SHOPIFYIGNORE_CONTENT, which, } from '../lib/scaffold.js';
+export default class CreateProject extends Command {
+    static args = {
+        shop: Args.string({ description: 'Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)', required: false }),
+    };
+    static description = 'Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.\n\nGitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI never stores credentials. Override the org with FND_GH_ORG.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> my-store',
+        '<%= config.bin %> <%= command.id %> my-store "Acme storefront, Klaviyo"',
+    ];
+    // Everything after the shop handle is collected as free-form hints for Claude.
+    static strict = false;
+    async run() {
+        const { argv } = await this.parse(CreateProject);
+        const [shop, ...rest] = argv;
+        const hints = rest.join(' ');
+        const git = simpleGit();
+        // 1. git init on branch 'production'
+        if (existsSync(join(process.cwd(), '.git'))) {
+            this.log(chalk.blue('ℹ️  git repo already initialized — leaving the current branch as-is'));
+        }
+        else {
+            await git.raw(['init', '-b', 'production']);
+            this.log(chalk.green("✅ git initialized on branch 'production'"));
+        }
+        // 2. ignore files (always written, matching the original scaffold)
+        writeFileSync('.gitignore', GITIGNORE_CONTENT);
+        writeFileSync('.shopifyignore', SHOPIFYIGNORE_CONTENT);
+        this.log(chalk.green('✅ .gitignore and .shopifyignore created'));
+        // 3. Pull the live Shopify theme so Claude can inspect real files when it
+        // writes CLAUDE.md. Only runs when a shop handle was passed.
+        if (shop) {
+            const shopifyBin = findShopifyBin();
+            if (shopifyBin) {
+                // Prepend the binary's own dir so its `env node` shebang resolves to
+                // the node it was installed with, not an older active version.
+                this.log(chalk.blue(`🎨 Pulling Shopify theme from store '${shop}' (via ${shopifyBin})…`));
+                const env = { ...process.env, PATH: `${dirname(shopifyBin)}:${process.env.PATH}` };
+                await run(shopifyBin, ['theme', 'pull', `--store=${shop}`], env);
+            }
+            else {
+                this.log(chalk.blue(`ℹ️  shopify CLI not found — run manually: shopify theme pull --store=${shop}`));
+            }
+        }
+        // 4. CLAUDE.md via Claude (skipped with a warning when claude isn't
+        // installed — the GitHub step below still runs)
+        this.log(chalk.blue('🤖 Generating CLAUDE.md with Claude…'));
+        const claudeResult = await generateClaudeMd(shop, hints);
+        switch (claudeResult) {
+            case 'claude-not-installed': {
+                this.warn('claude CLI not found — skipping CLAUDE.md. Install it with: npm install -g @anthropic-ai/claude-code');
+                break;
+            }
+            case 'missing-prompt': {
+                this.error(`bundled prompt missing at ${initPromptPath()} — try reinstalling @firenet-designs/fnd-cli`, { code: '1' });
+                break;
+            }
+            case 'not-written': {
+                this.warn('Claude finished but no CLAUDE.md was found — check the output above');
+                break;
+            }
+            case 'written': {
+                this.log(chalk.green(`✅ CLAUDE.md written to ${process.cwd()}`));
+                break;
+            }
+        }
+        // 5. Private GitHub repo. The create-only token (GH_TOKEN) is used by gh
+        // for the API call only; the push goes over SSH with the user's own key.
+        if (!which('gh')) {
+            this.log(chalk.blue('ℹ️  gh not installed — skipping GitHub. Install with: brew install gh'));
+            return;
+        }
+        const hasTokenInEnv = Boolean(process.env.GH_TOKEN || process.env.GITHUB_TOKEN);
+        const ghAuthenticated = spawnSync('gh', ['auth', 'status'], { stdio: 'ignore' }).status === 0;
+        if (!hasTokenInEnv && !ghAuthenticated) {
+            this.log(chalk.yellow('⚠️  No GitHub auth found — skipping repo creation. Set it up once, then re-run:'));
+            this.log(chalk.yellow('   • easiest:  gh auth login'));
+            this.log(chalk.yellow('   • or add to your shell profile (~/.zshrc):  export GH_TOKEN=<fine-grained PAT>'));
+            this.log(chalk.yellow('     (PAT only needs repo-create on the FireNet-Designs org — push goes over your SSH key)'));
+            return;
+        }
+        const remotes = await git.getRemotes();
+        if (remotes.some((r) => r.name === 'origin')) {
+            this.log(chalk.blue("ℹ️  remote 'origin' already set — skipping GitHub repo creation"));
+            return;
+        }
+        const org = process.env.FND_GH_ORG || 'FireNet-Designs';
+        const repo = `${org}/${basename(process.cwd())}`;
+        this.log(chalk.blue('📦 Committing initial scaffold…'));
+        await git.raw(['add', '-A']);
+        try {
+            await git.raw(['commit', '-q', '-m', 'initial commit']);
+        }
+        catch {
+            this.error('nothing to commit — aborting GitHub step', { code: '1' });
+        }
+        this.log(chalk.blue(`🐙 Creating private GitHub repo '${repo}'…`));
+        const createCode = await run('gh', ['repo', 'create', repo, '--private', '--source=.', '--remote=origin']);
+        if (createCode !== 0) {
+            this.error('gh repo create failed — see output above', { code: '1' });
+        }
+        // Force SSH so the push authenticates with the user's key, not the
+        // create-only token.
+        await git.raw(['remote', 'set-url', 'origin', `git@github.com:${repo}.git`]);
+        this.log(chalk.blue("⬆️  Pushing 'production' to origin over SSH…"));
+        const pushCode = await run('git', ['push', '-u', 'origin', 'production']);
+        if (pushCode === 0) {
+            spawnSync('gh', ['repo', 'edit', repo, '--default-branch', 'production'], { stdio: 'ignore' });
+            this.log(chalk.green(`✅ Created + pushed. origin = git@github.com:${repo}.git`));
+        }
+        else {
+            this.warn(`push failed — check your SSH access to the ${org} org`);
+        }
+    }
+}

package/dist/commands/token.d.ts

@@ -0,0 +1,22 @@
+import { Command } from '@oclif/core';
+export default class Token extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'client-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'client-secret': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-open': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        scopes: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        store: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        write: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private mcpSnippet;
+    /** Loud, boxed reminder of the one-time Dev Dashboard setup. */
+    private printSetupBanner;
+    /** Minimal readline prompt — keeps the CLI dependency-free. */
+    private prompt;
+    private runOAuthFlow;
+    private writeMcpConfig;
+}

package/dist/commands/token.js

@@ -0,0 +1,224 @@
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { exec } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { platform, stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import ora from 'ora';
+/**
+ * The Shopify `client_credentials` grant only works for apps and stores that
+ * live in the SAME Dev Dashboard org. For a client's paid store in another org
+ * it returns `shop_not_permitted`. This command runs the interactive
+ * authorization-code grant instead, which works cross-org and mints a permanent
+ * OFFLINE access token usable as `--access-token` by Shopify Admin tooling.
+ */
+const DEFAULT_PORT = 3456;
+const DEFAULT_SCOPES = 'read_products';
+/** `mystore` or `https://mystore.myshopify.com/` -> `mystore.myshopify.com`. */
+const normalizeStore = (raw) => {
+    const host = raw.trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    return host.endsWith('.myshopify.com') ? host : `${host}.myshopify.com`;
+};
+/** Open a URL in the user's default browser (best-effort, never throws). */
+const openBrowser = (url) => {
+    const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start ""' : 'xdg-open';
+    exec(`${cmd} "${url}"`, () => { });
+};
+export default class Token extends Command {
+    static description = 'Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works cross-org, unlike client_credentials.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --store trafalgar-store --client-id 0b42... --client-secret shpss_...',
+        '<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --scopes read_products,read_orders',
+        '<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --write ./.mcp.json',
+    ];
+    static flags = {
+        'client-id': Flags.string({ char: 'i', description: 'app Client ID' }),
+        'client-secret': Flags.string({ char: 'c', description: 'app Client secret (shpss_...)' }),
+        'no-open': Flags.boolean({ description: "don't auto-open the authorize URL in a browser" }),
+        port: Flags.integer({ char: 'p', default: DEFAULT_PORT, description: 'local callback port (must match the app redirect URL)' }),
+        scopes: Flags.string({ default: DEFAULT_SCOPES, description: 'comma-separated Admin API scopes to request' }),
+        store: Flags.string({ char: 's', description: 'store domain (mystore or mystore.myshopify.com)' }),
+        write: Flags.string({ char: 'w', description: "path to an .mcp.json whose 'shopify' server should be rewritten to use the token" }),
+    };
+    async run() {
+        const { flags } = await this.parse(Token);
+        const store = normalizeStore(flags.store ?? (await this.prompt('Store domain (e.g. mystore)')));
+        const clientId = flags['client-id'] ?? (await this.prompt('Client ID'));
+        const clientSecret = flags['client-secret'] ?? (await this.prompt('Client secret (shpss_...)'));
+        const { scopes } = flags;
+        const { port } = flags;
+        const redirectUri = `http://localhost:${port}/callback`;
+        this.printSetupBanner(redirectUri, scopes);
+        const token = await this.runOAuthFlow({ clientId, clientSecret, open: !flags['no-open'], port, redirectUri, scopes, store });
+        this.log('');
+        this.log(chalk.green('✓ Offline access token (never expires until uninstall/secret rotation):'));
+        this.log('  ' + chalk.bold(token));
+        this.log('');
+        this.log(chalk.dim('Drop-in .mcp.json server config:'));
+        this.log(this.mcpSnippet(store, token));
+        if (flags.write) {
+            this.writeMcpConfig(flags.write, store, token);
+            this.log('');
+            this.log(chalk.green(`✓ Updated ${flags.write} (shopify server -> --access-token).`));
+        }
+    }
+    mcpSnippet(store, token) {
+        const config = {
+            mcpServers: {
+                shopify: {
+                    args: ['-y', 'shopify-graphql-admin-mcp', '--store', store, '--access-token', token],
+                    command: 'npx',
+                },
+            },
+        };
+        return chalk.dim(JSON.stringify(config, null, 2));
+    }
+    /** Loud, boxed reminder of the one-time Dev Dashboard setup. */
+    printSetupBanner(redirectUri, scopes) {
+        const rows = [
+            { kind: 'header', text: '⚠  ONE-TIME APP SETUP — in the Shopify Dev Dashboard' },
+            { kind: 'body', text: '' },
+            { kind: 'body', text: 'The custom app for this store MUST have BOTH of these,' },
+            { kind: 'body', text: 'or Shopify shows an error instead of an approve screen:' },
+            { kind: 'body', text: '' },
+            { kind: 'body', text: '1) Add this Redirect URL to the app (exactly):' },
+            { kind: 'value', text: `     ${redirectUri}` },
+            { kind: 'body', text: '2) Release a version with this scope:' },
+            { kind: 'value', text: `     ${scopes}` },
+        ];
+        const width = Math.max(...rows.map((r) => r.text.length));
+        const bar = '─'.repeat(width + 2);
+        this.log('');
+        this.log(chalk.yellow.bold(`┌${bar}┐`));
+        for (const row of rows) {
+            const padded = ` ${row.text.padEnd(width)} `;
+            let body;
+            if (row.kind === 'header')
+                body = chalk.bgYellow.black.bold(padded);
+            else if (row.kind === 'value')
+                body = chalk.cyanBright.bold(padded);
+            else
+                body = chalk.yellow(padded);
+            this.log(chalk.yellow.bold('│') + body + chalk.yellow.bold('│'));
+        }
+        this.log(chalk.yellow.bold(`└${bar}┘`));
+        this.log('');
+    }
+    /** Minimal readline prompt — keeps the CLI dependency-free. */
+    async prompt(label) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            const answer = (await rl.question(`${label}: `)).trim();
+            if (!answer)
+                this.error(`${label} is required`, { code: '1' });
+            return answer;
+        }
+        finally {
+            rl.close();
+        }
+    }
+    runOAuthFlow(opts) {
+        const { clientId, clientSecret, open, port, redirectUri, scopes, store } = opts;
+        const state = randomBytes(16).toString('hex');
+        const authorizeUrl = `https://${store}/admin/oauth/authorize` +
+            `?client_id=${encodeURIComponent(clientId)}` +
+            `&scope=${encodeURIComponent(scopes)}` +
+            `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+            `&state=${state}`;
+        const spinner = ora(`Waiting for authorization at ${redirectUri} …`);
+        return new Promise((resolve, reject) => {
+            const server = createServer(async (req, res) => {
+                const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+                if (url.pathname !== '/callback') {
+                    res.writeHead(404).end('not found');
+                    return;
+                }
+                const code = url.searchParams.get('code');
+                const returnedState = url.searchParams.get('state');
+                const oauthError = url.searchParams.get('error');
+                const fail = (message, httpBody) => {
+                    res.writeHead(400, { 'Content-Type': 'text/html' }).end(httpBody);
+                    spinner.fail(message);
+                    server.close();
+                    reject(new Error(message));
+                };
+                // Ignore spurious/stale hits — a bare probe, or a leftover browser tab
+                // from a previous run replaying an old callback on this same port.
+                // These must NOT abort the flow; only a callback carrying OUR exact
+                // state is allowed to proceed.
+                if (!code && !oauthError) {
+                    res.writeHead(204).end();
+                    return;
+                }
+                if (returnedState !== state) {
+                    res.writeHead(409, { 'Content-Type': 'text/html' }).end('<h2>Stale authorization tab — ignore this and use the newest link from your terminal.</h2>');
+                    spinner.text = 'Ignored a stale/mismatched callback (likely an old browser tab). Still waiting …';
+                    return;
+                }
+                if (oauthError)
+                    return fail(`Authorization denied: ${oauthError}.`, '<h2>Authorization denied.</h2>');
+                if (!code)
+                    return fail('No authorization code returned.', '<h2>No authorization code returned.</h2>');
+                try {
+                    const tokenRes = await fetch(`https://${store}/admin/oauth/access_token`, {
+                        // Shopify's token endpoint requires these exact snake_case keys.
+                        // eslint-disable-next-line camelcase
+                        body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, code }),
+                        headers: { 'Content-Type': 'application/json' },
+                        method: 'POST',
+                    });
+                    const text = await tokenRes.text();
+                    if (!tokenRes.ok)
+                        return fail(`Token exchange failed (${tokenRes.status}): ${text.slice(0, 200)}`, '<h2>Token exchange failed. Check the terminal.</h2>');
+                    const data = JSON.parse(text);
+                    res.writeHead(200, { 'Content-Type': 'text/html' }).end('<h2>✅ Token captured. Return to the terminal.</h2>');
+                    spinner.succeed('Authorization complete.');
+                    server.close();
+                    resolve(data.access_token);
+                }
+                catch (error) {
+                    fail(`Error during token exchange: ${error.message}`, '<h2>Error. Check the terminal.</h2>');
+                }
+            });
+            // Don't wait forever; clear on close so any exit path stops the timer.
+            const timer = setTimeout(() => {
+                spinner.fail('Timed out after 5 minutes waiting for authorization.');
+                server.close();
+                reject(new Error('Timed out waiting for authorization.'));
+            }, 300_000);
+            timer.unref();
+            server.on('close', () => clearTimeout(timer));
+            server.on('error', (error) => {
+                clearTimeout(timer);
+                const message = error.code === 'EADDRINUSE'
+                    ? `Port ${port} is already in use — a previous run may still hold it. Kill it, or pass a different --port (and add that redirect URL to the app).`
+                    : error.message;
+                reject(new Error(message));
+            });
+            server.listen(port, () => {
+                this.log(chalk.dim('Open this URL to authorize (logged into the store admin):'));
+                this.log('  ' + chalk.cyan(authorizeUrl));
+                if (open)
+                    openBrowser(authorizeUrl);
+                spinner.start();
+            });
+        });
+    }
+    writeMcpConfig(path, store, token) {
+        let json;
+        try {
+            json = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (error) {
+            this.error(`Could not read ${path}: ${error.message}`, { code: '1' });
+        }
+        json.mcpServers ??= {};
+        json.mcpServers.shopify = {
+            args: ['-y', 'shopify-graphql-admin-mcp', '--store', store, '--access-token', token],
+            command: 'npx',
+        };
+        writeFileSync(path, JSON.stringify(json, null, 2) + '\n');
+    }
+}

package/dist/lib/scaffold.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared scaffolding pieces for `create-project` and `backfill-project`.
+ *
+ * SECURITY: nothing in this module (or the commands that use it) may ever
+ * contain, read into a string, or print a credential. GitHub auth comes from
+ * the user's own environment (GH_TOKEN / GITHUB_TOKEN exported in their shell,
+ * or `gh auth login`) — we only check that SOME auth exists, never the value.
+ */
+export declare const GITIGNORE_CONTENT = ".idea/\nnode_modules/\nconfig.yml\n";
+export declare const SHOPIFYIGNORE_CONTENT = "src/\nscripts/\nsrc\nscripts\nconfig.yml\n";
+/**
+ * Prompt that drives CLAUDE.md generation. Ships with this package in
+ * prompts/ (resolved relative to this module: dist/lib -> <pkg root>/prompts).
+ * Set FND_INIT_PROMPT_PATH to test a local prompt without republishing.
+ */
+export declare const initPromptPath: () => string;
+/**
+ * Runs a command with stdio inherited so the user sees live output and can
+ * answer interactive prompts (shopify auth, claude, gh, git/ssh).
+ */
+export declare const run: (command: string, args: string[], env?: NodeJS.ProcessEnv) => Promise<number>;
+/** Resolves a binary on PATH, or null if not found. */
+export declare const which: (bin: string) => null | string;
+/**
+ * Finds the shopify CLI: PATH first, then nvm node versions (newest wins) —
+ * shopify is often installed per nvm node version that isn't currently active.
+ */
+export declare const findShopifyBin: () => null | string;
+/**
+ * Builds the CLAUDE.md generation prompt and runs `claude -p` with it.
+ * Returns 'claude-not-installed' when the claude CLI isn't on PATH,
+ * 'missing-prompt' when the bundled prompt file is gone (broken install),
+ * otherwise 'written'/'not-written' depending on whether CLAUDE.md appeared.
+ */
+export declare const generateClaudeMd: (shop: string | undefined, extraHints: string) => Promise<"claude-not-installed" | "missing-prompt" | "not-written" | "written">;

package/dist/lib/scaffold.js

@@ -0,0 +1,101 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Shared scaffolding pieces for `create-project` and `backfill-project`.
+ *
+ * SECURITY: nothing in this module (or the commands that use it) may ever
+ * contain, read into a string, or print a credential. GitHub auth comes from
+ * the user's own environment (GH_TOKEN / GITHUB_TOKEN exported in their shell,
+ * or `gh auth login`) — we only check that SOME auth exists, never the value.
+ */
+export const GITIGNORE_CONTENT = `.idea/
+node_modules/
+config.yml
+`;
+export const SHOPIFYIGNORE_CONTENT = `src/
+scripts/
+src
+scripts
+config.yml
+`;
+/**
+ * Prompt that drives CLAUDE.md generation. Ships with this package in
+ * prompts/ (resolved relative to this module: dist/lib -> <pkg root>/prompts).
+ * Set FND_INIT_PROMPT_PATH to test a local prompt without republishing.
+ */
+export const initPromptPath = () => {
+    const override = process.env.FND_INIT_PROMPT_PATH;
+    if (override && existsSync(override))
+        return override;
+    return fileURLToPath(new URL('../../prompts/init-project-auto.md', import.meta.url));
+};
+/**
+ * Runs a command with stdio inherited so the user sees live output and can
+ * answer interactive prompts (shopify auth, claude, gh, git/ssh).
+ */
+export const run = (command, args, env) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env: env ?? process.env, stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('close', (code) => resolve(code ?? 1));
+});
+/** Resolves a binary on PATH, or null if not found. */
+export const which = (bin) => {
+    const result = spawnSync('which', [bin], { encoding: 'utf8' });
+    return result.status === 0 ? result.stdout.trim() : null;
+};
+const parseNodeVersion = (v) => v.replace(/^v/, '').split('.').map(Number);
+/** `sort -V` equivalent for nvm dir names like `v24.13.1`. */
+const compareNodeVersions = (a, b) => {
+    const [aParts, bParts] = [parseNodeVersion(a), parseNodeVersion(b)];
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const diff = (aParts[i] ?? 0) - (bParts[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+};
+/**
+ * Finds the shopify CLI: PATH first, then nvm node versions (newest wins) —
+ * shopify is often installed per nvm node version that isn't currently active.
+ */
+export const findShopifyBin = () => {
+    const onPath = which('shopify');
+    if (onPath)
+        return onPath;
+    const nodeVersionsDir = join(homedir(), '.nvm', 'versions', 'node');
+    if (!existsSync(nodeVersionsDir))
+        return null;
+    const versions = readdirSync(nodeVersionsDir)
+        .filter((v) => existsSync(join(nodeVersionsDir, v, 'bin', 'shopify')))
+        .sort(compareNodeVersions);
+    const newest = versions.at(-1);
+    return newest ? join(nodeVersionsDir, newest, 'bin', 'shopify') : null;
+};
+/**
+ * Builds the CLAUDE.md generation prompt and runs `claude -p` with it.
+ * Returns 'claude-not-installed' when the claude CLI isn't on PATH,
+ * 'missing-prompt' when the bundled prompt file is gone (broken install),
+ * otherwise 'written'/'not-written' depending on whether CLAUDE.md appeared.
+ */
+export const generateClaudeMd = async (shop, extraHints) => {
+    if (!which('claude'))
+        return 'claude-not-installed';
+    const promptPath = initPromptPath();
+    if (!existsSync(promptPath))
+        return 'missing-prompt';
+    let prompt = readFileSync(promptPath, 'utf8');
+    let hints = extraHints;
+    if (shop)
+        hints = `Shopify store: ${shop}. ${hints}`;
+    if (hints.trim())
+        prompt += `\n\n## User hints (override inference)\n${hints}`;
+    await run('claude', [
+        '-p', prompt,
+        '--permission-mode', 'acceptEdits',
+        '--allowedTools', 'Read Glob Grep Bash Write Edit',
+    ]);
+    return existsSync(join(process.cwd(), 'CLAUDE.md')) ? 'written' : 'not-written';
+};

package/oclif.manifest.json

@@ -1,5 +1,36 @@
 {
   "commands": {
+    "backfill-project": {
+      "aliases": [],
+      "args": {
+        "shop": {
+          "description": "Shopify store handle, passed to Claude as a hint",
+          "name": "shop",
+          "required": false
+        }
+      },
+      "description": "Backfill missing scaffold files in an EXISTING repo + theme: .gitignore, .shopifyignore, CLAUDE.md. Each is created only if absent — existing files are left untouched. Does NOT git init, pull the theme, commit, or touch GitHub.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-store",
+        "<%= config.bin %> <%= command.id %> my-store \"extra hints\""
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "backfill-project",
+      "pluginAlias": "@firenet-designs/fnd-cli",
+      "pluginName": "@firenet-designs/fnd-cli",
+      "pluginType": "core",
+      "strict": false,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "backfill-project.js"
+      ]
+    },
     "create-app": {
       "aliases": [],
       "args": {},
@@ -39,7 +70,119 @@
         "commands",
         "create-app.js"
       ]
+    },
+    "create-project": {
+      "aliases": [],
+      "args": {
+        "shop": {
+          "description": "Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)",
+          "name": "shop",
+          "required": false
+        }
+      },
+      "description": "Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.\n\nGitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI never stores credentials. Override the org with FND_GH_ORG.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-store",
+        "<%= config.bin %> <%= command.id %> my-store \"Acme storefront, Klaviyo\""
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "create-project",
+      "pluginAlias": "@firenet-designs/fnd-cli",
+      "pluginName": "@firenet-designs/fnd-cli",
+      "pluginType": "core",
+      "strict": false,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "create-project.js"
+      ]
+    },
+    "token": {
+      "aliases": [],
+      "args": {},
+      "description": "Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works cross-org, unlike client_credentials.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --store trafalgar-store --client-id 0b42... --client-secret shpss_...",
+        "<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --scopes read_products,read_orders",
+        "<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --write ./.mcp.json"
+      ],
+      "flags": {
+        "client-id": {
+          "char": "i",
+          "description": "app Client ID",
+          "name": "client-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "client-secret": {
+          "char": "c",
+          "description": "app Client secret (shpss_...)",
+          "name": "client-secret",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "no-open": {
+          "description": "don't auto-open the authorize URL in a browser",
+          "name": "no-open",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "port": {
+          "char": "p",
+          "description": "local callback port (must match the app redirect URL)",
+          "name": "port",
+          "default": 3456,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scopes": {
+          "description": "comma-separated Admin API scopes to request",
+          "name": "scopes",
+          "default": "read_products",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "store": {
+          "char": "s",
+          "description": "store domain (mystore or mystore.myshopify.com)",
+          "name": "store",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "write": {
+          "char": "w",
+          "description": "path to an .mcp.json whose 'shopify' server should be rewritten to use the token",
+          "name": "write",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "token",
+      "pluginAlias": "@firenet-designs/fnd-cli",
+      "pluginName": "@firenet-designs/fnd-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "token.js"
+      ]
     }
   },
-  "version": "1.1.1"
+  "version": "2.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firenet-designs/fnd-cli",
   "description": "A new CLI generated with oclif",
-  "version": "1.1.1",
+  "version": "2.1.0",
   "author": "Cole Denslow",
   "bin": {
     "fnd": "bin/run.js"
@@ -21,7 +21,7 @@
     "@oclif/test": "^4",
     "@types/chai": "^4",
     "@types/mocha": "^10",
-    "@types/node": "^18.19.130",
+    "@types/node": "^24.13.1",
     "chai": "^4",
     "eslint": "^9",
     "eslint-config-oclif": "^6",
@@ -33,11 +33,12 @@
     "typescript": "^5"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.0.0"
   },
   "files": [
     "./bin",
     "./dist",
+    "./prompts",
     "./oclif.manifest.json"
   ],
   "homepage": "https://github.com/FireNet-Designs/fnd-cli",
@@ -46,6 +47,10 @@
   ],
   "license": "MIT",
   "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "type": "module",
   "oclif": {
     "bin": "fnd-cli",

package/prompts/init-project-auto.md

@@ -0,0 +1,183 @@
+# Init Project (Auto) — Generate & Write CLAUDE.md, No Questions
+
+You are generating a `CLAUDE.md` for the code repo in the **current working directory** and writing it to disk at `./CLAUDE.md`. This is a non-interactive, one-shot run.
+
+## Hard rules
+
+- **Do NOT ask the user anything.** There is no human watching this run. Infer every field from the repo. Where you genuinely cannot infer a value, use the sensible default noted below — never a placeholder like `[fill in]`.
+- **Write the file yourself** to `./CLAUDE.md` using the Write tool. Do not print it in a code block and stop.
+- If `./CLAUDE.md` already exists, read it first and treat the run as an update: keep any human-written project notes, refresh the inferred sections.
+- Keep the whole thing tight. This file is loaded on every future session in the repo — no filler.
+
+## Step 1 — Inspect the repo (read-only)
+
+Look at the current directory to infer the fields. Useful signals:
+
+- `package.json` → name, scripts (dev/test/lint/typecheck/build/deploy), dependencies (stack + runtime via `engines`), entry (`main`/`module`/`exports`).
+- `shopify.app.toml` → **Shopify App**. Look for an `extensions/` dir → note each extension and its `shopify.extension.toml`.
+- `shopify.theme.toml`, or top-level `templates/ sections/ snippets/ layout/ config/` → **Shopify Theme**.
+- `@shopify/hydrogen` in deps, or `app/routes/` + `remix`/`vite` → **Shopify Hydrogen**.
+- `next.config.*` or `next` in deps → **Next.js**.
+- An Express/Fastify/Hono server entry with no frontend → **Node API**.
+- Anything else → **Custom** (write 4–6 conventions tailored to the actual stack).
+- `tsconfig.json`, lockfile type (`package-lock.json`/`pnpm-lock.yaml`/`yarn.lock`/`bun.lockb`), `.nvmrc`/`engines` → runtime + package manager.
+- `.env.example` / `.env.sample` → external services (Klaviyo, Stripe, Shopify Admin API, a DB URL, etc.).
+- Top two levels of the directory tree → Project Structure block.
+
+Defaults when a signal is missing: Type = `Custom`; Runtime = latest LTS Node; Build output = `none`; External Services = omit the section; commands = omit rows that don't exist.
+
+## Step 2 — Write `./CLAUDE.md` with exactly this structure
+
+```
+# [Project Name]
+
+**Type:** [Project Type]
+**Stack:** [Stack — comma separated]
+**Runtime:** [Runtime + package manager]
+
+## What This Is
+
+[One or two sentences inferred from README/package.json description. If none, describe it from the code.]
+
+---
+
+## Engineering Principles
+
+These apply to every file touched in this project.
+
+| Principle | Rule |
+|-----------|------|
+| Separation of concerns | One module, one reason to change |
+| No side effects at the core | Pure logic in the middle, IO/network/DB/filesystem only at the edges |
+| Open/Closed | Extend by adding — modify existing code only to fix bugs, never for a new caller |
+| WET before DRY | Duplicate until three identical-shape instances, then extract |
+| No unnecessary abstraction | If you can delete it and nothing breaks, delete it |
+| Boundary validation only | Validate user input and external API responses — trust internal code |
+| Comments explain WHY | Not what. Never describe what the code does. |
+
+---
+
+## Project Structure
+
+```
+[Top two levels of the directory tree]
+```
+
+**Entry point:** `[entry point]`
+**Build output:** `[build output]` — generated, never edit directly
+
+---
+
+## Conventions
+
+[Insert the matching preset block below for the detected type. For Custom, write 4–6 stack-specific rules, one per line, imperative voice.]
+
+---
+
+## Workflow
+
+| Task | Command |
+|------|---------|
+| Dev | `[dev]` |
+| Test | `[test]` |
+| Lint | `[lint]` |
+| Type check | `[typecheck]` |
+| Build | `[build]` |
+| Deploy | `[deploy]` |
+
+(Omit rows with no real command.)
+
+---
+
+## External Services
+
+[One line per service + what it's for. Omit this whole section if none.]
+
+---
+
+## Package Security
+
+- Never install a package younger than 14 days — let the community catch malicious releases first.
+- Read every install command before approving the dependencies it pulls in.
+
+---
+
+## Agent Behavior
+
+- **Never ask the user to test, run, or verify anything.** Claude owns the full dev loop — write, run, debug, fix, repeat until it works.
+- If something genuinely cannot be verified (e.g. a visual UI state), say so explicitly. Never claim success without verifying.
+- **Destructive commands require confirmation first.** Destructive = force push, `reset --hard`, deleting files/branches, dropping tables, removing packages, overwriting uncommitted work.
+- Everything else: just run it. For complex or non-obvious commands, give one line of context — then run without waiting.
+
+---
+
+## Do Not Touch
+
+- `[build output]` — generated output, never edit directly
+- `.env` / `.env.*` — never read or write secret values; use `.env.example` for shape only
+- Lockfiles — source of truth, never edit manually
+- `node_modules/` — never edit
+[Any extra off-limits dirs you spotted]
+```
+
+## Convention presets
+
+### Shopify Theme
+```
+- Liquid templates live in `templates/`, `sections/`, `snippets/`, `layout/`
+- CSS: `assets/[name].css`; JS: `assets/[name].js` — no bundler unless one is set up
+- `config/settings_data.json` is written by Shopify admin — read but treat as volatile
+- `config/settings_schema.json` is the source of truth for theme settings
+- Never inline styles or scripts in Liquid — use asset references
+- `{% schema %}` blocks must be valid JSON; verify with `shopify theme check`
+```
+
+### Shopify App
+```
+- App entry: `[entry]`; Shopify CLI manages tunneling + dev environment
+- `shopify.app.toml` — app config, commit it
+- Extensions live in `extensions/[name]/`, each with its own `shopify.extension.toml`
+- Never hardcode shop domain or access tokens — read from env or session
+- Webhook handlers must verify HMAC before processing
+```
+
+**If this is a Shopify App with extensions, ALSO append this block to the `Conventions` section verbatim:**
+```
+### Extension Constraints (hard platform limits)
+- **No third-party libraries inside extension code.** Extensions run in a constrained sandbox — write plain code, no npm deps bundled into the extension.
+- Hard limits per extension: **128 kB input / 11M instructions / 20 kB output.** Exceeding any of these fails the function at runtime.
+- Keep extension logic minimal and allocation-free in hot paths; do work in the app backend where possible.
+```
+
+### Shopify Hydrogen
+```
+- Remix file routing: `app/routes/` maps 1:1 to URL segments
+- Loaders run server-side; actions handle mutations
+- Storefront API queries live in `app/graphql/` as `.graphql` files
+- Set cache headers in the loader return — never skip them on product/collection routes
+- `public/` is served as-is; `app/assets/` goes through Vite
+```
+
+### Next.js
+```
+- App Router: `app/`; `page.tsx` = route, `layout.tsx` = shell
+- Server Components by default — add `"use client"` only when necessary
+- API routes: `app/api/[route]/route.ts`
+- Only `NEXT_PUBLIC_`-prefixed env vars are client-visible
+- Always use `next/image` for content images, never raw `<img>`
+- Never fetch in a Client Component when a Server Component can do it
+```
+
+### Node API
+```
+- Route handlers in `src/routes/`, one file per resource
+- Middleware in `src/middleware/`, applied in `src/app.ts`
+- Validate request bodies at the route boundary only — not inside service functions
+- Service functions are pure: typed inputs, typed outputs
+- Database access only inside `src/db/` or `src/repositories/` — never in routes
+- Environment config loaded once in `src/config.ts`
+```
+
+## Step 3 — Confirm
+
+After writing, print one line: the absolute path of the file written and the detected project type. Nothing else.