piezas 0.2.0

package/src/index.js

@@ -0,0 +1,2000 @@
+#!/usr/bin/env node
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { execSync, spawn } from 'child_process';
+import { homedir } from 'os';
+import { basename, dirname, extname, join, relative, resolve } from 'path';
+import { createInterface } from 'readline';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Human-facing progress output. init --json redirects this to stderr so stdout
+// stays machine-readable.
+let emit = (message) => console.log(message);
+function log(message) {
+  emit(message);
+}
+
+export const DEFAULT_API_BASE_URL = 'https://api.piezas.ai';
+// The gateway routes admin-api (the control plane) under {apiBase}/admin —
+// the same base the SDK instructions use for adminUrl.
+const ADMIN_PATH_PREFIX = '/admin';
+const HTTP_TIMEOUT_MS = 10_000;
+const API_KEY_FORMAT = /^sk_(live|test)_[A-Za-z0-9]{8,}$/;
+const ENV_KEY_LINE = /^\s*(?:export\s+)?PIEZAS_API_KEY\s*=\s*(.*)$/;
+const WAIT_FILE_CANDIDATES = ['.env', '.env.download', 'env.txt'];
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 300;
+const DEFAULT_WAIT_INTERVAL_MS = 2000;
+const KEY_PROMPT = 'Paste your Piezas API key (dashboard -> API Keys), or press Enter to skip: ';
+
+const PIEZAS_CONTEXT_START = '<!-- PIEZAS-CONTEXT:START -->';
+const PIEZAS_CONTEXT_END = '<!-- PIEZAS-CONTEXT:END -->';
+const PIEZAS_SPEC_START = '<!-- PIEZAS-SPEC:START -->';
+const PIEZAS_INSTRUCTIONS_BODY = readFileSync(
+  resolve(__dirname, 'templates', 'piezas-instructions.md'),
+  'utf-8',
+).trim();
+const PIEZAS_INSTRUCTIONS = `${PIEZAS_CONTEXT_START}\n${PIEZAS_INSTRUCTIONS_BODY}\n${PIEZAS_CONTEXT_END}\n`;
+const PIEZAS_SPEC_INSTRUCTIONS = `${readFileSync(
+  resolve(__dirname, 'templates', 'piezas-spec.md'),
+  'utf-8',
+).trim()}\n`;
+
+const DEFAULT_EXCLUDED_DIRS = new Set([
+  '.git',
+  '.next',
+  '.turbo',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+]);
+const TEXT_EXTENSIONS = new Set([
+  '.cjs',
+  '.css',
+  '.cts',
+  '.env',
+  '.js',
+  '.json',
+  '.jsx',
+  '.md',
+  '.mdc',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx',
+  '.yml',
+  '.yaml',
+]);
+const CODE_EXTENSIONS = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx']);
+const LOCAL_DB_PACKAGES = [
+  '@prisma/client',
+  'better-sqlite3',
+  'drizzle-orm',
+  'knex',
+  'mongoose',
+  'mysql2',
+  'pg',
+  'prisma',
+  'sequelize',
+  'sqlite',
+  'sqlite3',
+  'typeorm',
+];
+
+export const DEFAULT_DEPLOYMENT_MODE = 'next-bff';
+
+const MCP_ROUTE_PATH = 'app/api/piezas/mcp/route.ts';
+const NEXT_MCP_ROUTE_DEPLOYMENT_MODES = new Set(['next-bff', 'server-runtime']);
+
+export const RECIPE_PRESETS = {
+  'booking-site': {
+    slug: 'booking-site',
+    label: 'Public booking and appointment system',
+    owns: {
+      piezas: [
+        'tenantUsers',
+        'publicSessions',
+        'organizerProfiles',
+        'eventTypes',
+        'availabilityRules',
+        'bookings',
+        'inviteeAnswers',
+        'calendarConnections',
+        'meetingProviderConnections',
+        'bookingNotifications',
+        'auditEvents',
+      ],
+      app: ['bookingPageUi', 'adminScreens', 'timezonePresentation', 'routing'],
+    },
+    services: ['admin', 'entities', 'calendar', 'integrations', 'notifications', 'forms', 'workflow'],
+    setupOrder: [
+      'create tenant invite flow',
+      'connect calendar and meeting providers through Piezas Integrations',
+      'define organizer/event-type records',
+      'create availability rules',
+      'create public sessions for browser-safe booking flows',
+      'create bookings with server-side slot revalidation',
+    ],
+  },
+  'crm-project-finance': {
+    slug: 'crm-project-finance',
+    label: 'CRM, project tracking, and basic finance operations',
+    owns: {
+      piezas: [
+        'contacts',
+        'companies',
+        'deals',
+        'projects',
+        'tasks',
+        'invoices',
+      'receipts',
+      'bills',
+      'bankTransactions',
+      'accountingAccounts',
+      'ledgerEntries',
+      'reconciliationLinks',
+        'documentExtractionJobs',
+        'signatureRequests',
+        'documents',
+        'auditEvents',
+      ],
+      app: ['workspaceUi', 'recordLayouts', 'approvalFlows', 'reportViews'],
+    },
+    services: ['entities', 'pipeline', 'tasks', 'documents', 'pricing', 'reporting', 'workflow', 'integrations'],
+    setupOrder: [
+      'install CRM/project/finance entity patterns',
+      'define deal and project pipelines',
+      'store invoices and receipts as entity records linked to documents',
+      'store bills, bank transactions, finance accounts, and reconciliation links as entity records',
+      'store ledger entries and reconciliation links as Piezas entity records using SDK invariant helpers',
+      'create document extraction jobs in Piezas Documents before invoking OCR integration actions',
+      'create signature requests in Piezas Documents before invoking e-signature provider actions',
+      'use integration actions for OCR, accounting exports, and payment-provider references',
+      'use workflow sync jobs for imports, reconciliation, reminders, external accounting sync, and reports',
+    ],
+  },
+  'client-services-os': {
+    slug: 'client-services-os',
+    label: 'Client services operating system',
+    owns: {
+      piezas: [
+        'clients',
+        'projects',
+        'cases',
+        'tasks',
+        'documents',
+        'discussions',
+        'appointments',
+        'forms',
+        'signatureRequests',
+        'knowledgeBase',
+        'auditEvents',
+      ],
+      app: ['portalUi', 'clientDashboard', 'staffWorkspace', 'routing'],
+    },
+    services: ['admin', 'entities', 'tasks', 'calendar', 'documents', 'discussion', 'forms', 'knowledge-base', 'workflow'],
+    setupOrder: [
+      'create invite-only tenant/user access',
+      'define client, project, and case records',
+      'link tasks, discussions, documents, forms, and bookings back to client records',
+      'store signature-request state as Piezas records and use integrations for external signature providers',
+      'use public sessions for client-facing portal actions',
+      'use audit events for client-visible and staff-visible state changes',
+    ],
+  },
+};
+
+function normalizeRecipeList(value) {
+  const values = Array.isArray(value) ? value : value ? [value] : [];
+  return values
+    .flatMap((item) => String(item).split(','))
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function recipeManifest(slug) {
+  return RECIPE_PRESETS[slug] ?? {
+    slug,
+    label: slug,
+    owns: { piezas: [], app: [] },
+    services: [],
+    setupOrder: [],
+    notes: ['Custom recipe placeholder. Extend this manifest before implementation.'],
+  };
+}
+
+function supportsMcpRoute(deploymentMode) {
+  return NEXT_MCP_ROUTE_DEPLOYMENT_MODES.has(deploymentMode);
+}
+
+function mcpManifest(options = {}) {
+  const deploymentMode = options.deploymentMode || DEFAULT_DEPLOYMENT_MODE;
+  const requested = Boolean(options.mcp);
+  const enabled = requested && supportsMcpRoute(deploymentMode);
+
+  return {
+    requested,
+    enabled,
+    sdkExport: 'piezasMcp',
+    routePath: enabled ? MCP_ROUTE_PATH : null,
+    availableTools: ['entity-records', 'pipeline', 'tasks'],
+    appMustProvide: ['sessionAuth', 'tenantContext', 'userContext', 'routeAccessControl'],
+    note: enabled
+      ? 'Protect the MCP route with app auth before exposing it to users or agents.'
+      : 'Use `npx piezas init --mcp --mode next-bff` or mount `piezasMcp` in a server runtime when agent tool access is needed.',
+  };
+}
+
+export function buildDefaultManifest(options = {}) {
+  const deploymentMode = options.deploymentMode || DEFAULT_DEPLOYMENT_MODE;
+  const recipes = normalizeRecipeList(options.recipes ?? options.recipe)
+    .map(recipeManifest);
+  return {
+    $schema: 'https://piezas.ai/schemas/piezas-manifest.schema.json',
+    schemaVersion: 1,
+    generatedBy: 'piezas',
+    appName: options.appName ?? null,
+    apiBaseUrl: options.apiBaseUrl || DEFAULT_API_BASE_URL,
+    productType: options.productType || 'custom-app',
+    deploymentMode,
+    piezasOwns: [
+      'businessRecords',
+      'crmRecords',
+      'accountingRecords',
+      'ledgerEntryRecords',
+      'reconciliationRecords',
+      'documentExtractionRecords',
+      'signatureRequestRecords',
+      'financeAccounts',
+      'bills',
+      'bankTransactions',
+      'calendarAvailability',
+      'bookings',
+      'integrationConnections',
+      'integrationAppRegistry',
+      'integrationCredentials',
+      'integrationAppPolicies',
+      'integrationGrants',
+      'integrationTokenRefresh',
+      'notifications',
+      'workflowState',
+      'durableJobs',
+      'syncJobs',
+      'jobLockState',
+      'mcpToolDiscovery',
+      'publicSessions',
+      'auditEvents',
+      'accessLogs',
+      'filesAndDocuments',
+      'reportingData',
+      'searchImportExport',
+    ],
+    appOwns: [
+      'ui',
+      'routing',
+      'sessionGlue',
+      'mcpRouteAccessControl',
+      'workflowOrchestration',
+      'viewState',
+    ],
+    serverOnlySecrets: [
+      'PIEZAS_API_KEY',
+      'NEXTAUTH_SECRET',
+      'AUTH_SECRET',
+      'SESSION_SECRET',
+      'ADMIN_TOKEN',
+      'ADMIN_PASS',
+      'GOOGLE_CLIENT_SECRET',
+      'ZOOM_CLIENT_SECRET',
+    ],
+    integrationPolicy: {
+      piezasOwns: [
+        'providerClientConfig',
+        'appScopedProviderClientConfig',
+        'appAllowedOrigins',
+        'appAllowedRedirectUris',
+        'appConnectorPurposePolicy',
+        'providerActionCatalog',
+        'oauthCallbacks',
+        'encryptedAccessTokens',
+        'encryptedRefreshTokens',
+        'tokenRefresh',
+        'syncCursors',
+        'connectionGrants',
+        'documentExtractionJobs',
+        'signatureRequests',
+      ],
+      appStoresOnly: ['appIds', 'connectionIds', 'grantIds', 'externalRecordRefs'],
+      appScopedOAuth:
+        'Create a Piezas tenant app for each generated app/domain/use case, save provider client config with appId and purpose, and pass appId/purpose on OAuth start and connection lookup.',
+      payments: 'Use provider integrations for payment links or references; Piezas does not process money.',
+    },
+    recommendedPatterns: [
+      'relationships',
+      'ledger',
+      'accounting-postings',
+      'reconciliation',
+      'thin-server-adapter',
+      'sdk-mcp-route',
+      'public-sessions',
+      'durable-jobs',
+      'sync-jobs',
+    ],
+    mcp: mcpManifest({ deploymentMode, mcp: options.mcp }),
+    publicRoutes: [],
+    recipes,
+    notes: [
+      'Future recipes should extend this manifest instead of replacing it.',
+      'Run `npx piezas doctor` after AI-generated changes.',
+    ],
+  };
+}
+
+// Flags that never take a value — they must not swallow a following
+// positional (e.g. `piezas init --wait mydir` targets mydir/).
+const BOOLEAN_FLAGS = new Set([
+  'fromLogin',
+  'json',
+  'mcp',
+  'noDeps',
+  'skipDeps',
+  'skipInstall',
+  'strict',
+  'wait',
+  'yes',
+]);
+
+export function parseCliArgs(args) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split('=');
+    const key = rawKey.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+    if (inlineValue !== undefined) {
+      flags[key] = appendFlagValue(flags[key], inlineValue);
+    } else if (!BOOLEAN_FLAGS.has(key) && args[i + 1] && !args[i + 1].startsWith('--')) {
+      flags[key] = appendFlagValue(flags[key], args[i + 1]);
+      i += 1;
+    } else {
+      flags[key] = appendFlagValue(flags[key], true);
+    }
+  }
+
+  return { flags, positional };
+}
+
+function appendFlagValue(existing, value) {
+  if (existing === undefined) return value;
+  return Array.isArray(existing) ? [...existing, value] : [existing, value];
+}
+
+// spliceMarkerBlock replaces the START..END block inside `existing` with the
+// block from `content`, preserving any user content around the markers. Falls
+// back to a full replace when the block cannot be located on both sides.
+function spliceMarkerBlock(existing, content, startMarker, endMarker) {
+  if (!endMarker) return content;
+  const start = existing.indexOf(startMarker);
+  const end = existing.indexOf(endMarker, start);
+  const newStart = content.indexOf(startMarker);
+  const newEnd = content.indexOf(endMarker, newStart);
+  if (start < 0 || end < 0 || newStart < 0 || newEnd < 0) return content;
+  return (
+    existing.slice(0, start) +
+    content.slice(newStart, newEnd + endMarker.length) +
+    existing.slice(end + endMarker.length)
+  );
+}
+
+function writeIfNew(filePath, content, label, options = {}) {
+  const startMarker = options.startMarker || PIEZAS_CONTEXT_START;
+  const endMarker = options.endMarker ?? (startMarker === PIEZAS_CONTEXT_START ? PIEZAS_CONTEXT_END : undefined);
+  const appendIfNoMarker = options.appendIfNoMarker ?? true;
+
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf-8');
+    if (existing === content) {
+      log(`  ${label} is up to date - skipping`);
+      return;
+    }
+    if (existing.includes(startMarker)) {
+      const updated = spliceMarkerBlock(existing, content, startMarker, endMarker);
+      if (updated === existing) {
+        log(`  ${label} is up to date - skipping`);
+        return;
+      }
+      writeFileSync(filePath, updated);
+      log(`  Updated ${label}`);
+      return;
+    }
+    if (!appendIfNoMarker) {
+      log(`  ${label} exists - skipping`);
+      return;
+    }
+    writeFileSync(filePath, `${existing.trimEnd()}\n\n${content}`);
+    log(`  Updated ${label}`);
+  } else {
+    writeFileSync(filePath, content);
+    log(`  Created ${label}`);
+  }
+}
+
+function writeFileIfMissing(filePath, content, label) {
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf-8');
+    if (existing === content) {
+      log(`  ${label} is up to date - skipping`);
+    } else {
+      log(`  ${label} exists - skipping`);
+    }
+    return false;
+  }
+
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content);
+  log(`  Created ${label}`);
+  return true;
+}
+
+// upsertManifest creates piezas.manifest.json when missing, or extends an
+// existing one with app metadata (appName, apiBaseUrl) without touching any
+// other field the project may have customized.
+function upsertManifest(manifestPath, buildOptions) {
+  if (!existsSync(manifestPath)) {
+    const manifest = buildDefaultManifest(buildOptions);
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    log('  Created piezas.manifest.json');
+    return manifest;
+  }
+
+  let manifest;
+  try {
+    manifest = readJsonFile(manifestPath);
+  } catch {
+    log('  piezas.manifest.json is not valid JSON - leaving it untouched');
+    return null;
+  }
+
+  let changed = false;
+  if (buildOptions.appName && manifest.appName !== buildOptions.appName) {
+    manifest.appName = buildOptions.appName;
+    changed = true;
+  }
+  if (manifest.appName === undefined) {
+    manifest.appName = null;
+    changed = true;
+  }
+  if (manifest.apiBaseUrl === undefined) {
+    manifest.apiBaseUrl = DEFAULT_API_BASE_URL;
+    changed = true;
+  }
+
+  if (changed) {
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    log('  Updated piezas.manifest.json (app metadata)');
+  } else {
+    log('  piezas.manifest.json is up to date - skipping');
+  }
+  return manifest;
+}
+
+function mcpRouteContent() {
+  return `import { piezasMcp } from '@piezas/sdk';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+const handler = piezasMcp({
+  entitiesUrl: process.env.PIEZAS_ENTITIES_URL || 'https://api.piezas.ai/entities',
+  pipelineUrl: process.env.PIEZAS_PIPELINE_URL || 'https://api.piezas.ai/pipeline',
+  tasksUrl: process.env.PIEZAS_TASKS_URL || 'https://api.piezas.ai/tasks',
+  name: process.env.MCP_SERVER_NAME || 'piezas-app',
+});
+
+function requireMcpAccess(req: Request) {
+  const hasAppSession = Boolean(req.headers.get('authorization') || req.headers.get('cookie'));
+  const hasTenantContext = Boolean(req.headers.get('x-tenant-id') && req.headers.get('x-user-id'));
+  if (hasAppSession && hasTenantContext) return null;
+
+  return Response.json(
+    { error: 'MCP route requires app auth plus X-Tenant-Id and X-User-Id.' },
+    { status: 401 },
+  );
+}
+
+export async function POST(req: Request) {
+  // Replace this guard with your app session/auth check before exposing MCP publicly.
+  const denied = requireMcpAccess(req);
+  if (denied) return denied;
+
+  return handler(req);
+}
+`;
+}
+
+function scaffoldMcpRoute(projectDir, deploymentMode, requested) {
+  if (!requested) {
+    return { enabled: false, routePath: null };
+  }
+
+  if (!supportsMcpRoute(deploymentMode)) {
+    if (deploymentMode === 'static') {
+      log('  Skipped MCP route: static deployment mode cannot host server routes.');
+    } else {
+      log('  Skipped MCP route: mount `piezasMcp` in your server framework for this deployment mode.');
+    }
+    return {
+      enabled: false,
+      routePath: null,
+      skippedReason: deploymentMode === 'static' ? 'static-deployment-mode' : 'manual-server-framework',
+    };
+  }
+
+  writeFileIfMissing(
+    resolve(projectDir, MCP_ROUTE_PATH),
+    mcpRouteContent(),
+    MCP_ROUTE_PATH,
+  );
+  return { enabled: true, routePath: MCP_ROUTE_PATH };
+}
+
+function packageNameFromDir(projectDir) {
+  const name = basename(projectDir)
+    .toLowerCase()
+    .replace(/^@/, '')
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return name || 'piezas-app';
+}
+
+function ensurePackageJson(projectDir) {
+  const pkgJsonPath = resolve(projectDir, 'package.json');
+  if (existsSync(pkgJsonPath)) {
+    return;
+  }
+
+  const pkg = {
+    name: packageNameFromDir(projectDir),
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+  };
+
+  writeFileSync(pkgJsonPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  log('  Created package.json');
+}
+
+function stripQuotes(value) {
+  const match = /^(['"])(.*)\1$/.exec(value);
+  return match ? match[2] : value;
+}
+
+// readEnvKeyValue returns the PIEZAS_API_KEY value from a dotenv-style file,
+// or undefined when the file or the line is absent.
+function readEnvKeyValue(filePath) {
+  if (!existsSync(filePath)) return undefined;
+  for (const line of readFileSync(filePath, 'utf-8').split(/\r?\n/)) {
+    const match = ENV_KEY_LINE.exec(line);
+    if (match) return stripQuotes(match[1].trim());
+  }
+  return undefined;
+}
+
+// writeEnvKey merges PIEZAS_API_KEY=<key> into the project .env: creates the
+// file, appends the line, or replaces ONLY the existing PIEZAS_API_KEY line.
+// Every other byte — including CRLF/LF line endings — is preserved.
+function writeEnvKey(envPath, key) {
+  if (!existsSync(envPath)) {
+    writeFileSync(envPath, `PIEZAS_API_KEY=${key}\n`);
+    return 'created';
+  }
+
+  const content = readFileSync(envPath, 'utf-8');
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const parts = content.split(/(\r?\n)/);
+  for (let i = 0; i < parts.length; i += 2) {
+    const match = ENV_KEY_LINE.exec(parts[i]);
+    if (!match) continue;
+    if (stripQuotes(match[1].trim()) === key) return 'kept';
+    parts[i] = `PIEZAS_API_KEY=${key}`;
+    writeFileSync(envPath, parts.join(''));
+    return 'replaced';
+  }
+
+  const needsNewline = content.length > 0 && !content.endsWith('\n');
+  writeFileSync(envPath, `${content}${needsNewline ? eol : ''}PIEZAS_API_KEY=${key}${eol}`);
+  return 'appended';
+}
+
+const GITIGNORE_ENV_PATTERNS = new Set(['.env', '/.env', '.env*', '*.env', '**/.env']);
+
+// ensureGitignore makes sure .env is git-ignored. Respects existing patterns
+// (.env, .env*, *.env, ...) and appends a "# piezas" section only when needed.
+function ensureGitignore(projectDir) {
+  const gitignorePath = resolve(projectDir, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, '# piezas\n.env\n');
+    log('  Created .gitignore (.env ignored)');
+    return true;
+  }
+
+  const content = readFileSync(gitignorePath, 'utf-8');
+  const covered = content
+    .split(/\r?\n/)
+    .some((line) => GITIGNORE_ENV_PATTERNS.has(line.trim()));
+  if (covered) {
+    return false;
+  }
+
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  let updated = content;
+  if (updated.length > 0 && !updated.endsWith('\n')) updated += eol;
+  if (updated.length > 0) updated += eol;
+  updated += `# piezas${eol}.env${eol}`;
+  writeFileSync(gitignorePath, updated);
+  log('  Updated .gitignore (.env ignored)');
+  return true;
+}
+
+function promptViaTerminal(question) {
+  return new Promise((resolvePrompt) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolvePrompt(answer);
+    });
+  });
+}
+
+// waitForEnvKey polls the project dir for a dropped-in .env (or the names a
+// browser may give the dashboard download) containing PIEZAS_API_KEY.
+async function waitForEnvKey(projectDir, timeoutSeconds, intervalMs) {
+  log(`  Waiting for your API key: drop a ${WAIT_FILE_CANDIDATES.join(' or ')} file`);
+  log(`  containing PIEZAS_API_KEY into ${projectDir}`);
+  log(`  (dashboard -> API Keys -> "Download .env"). Checking every ${Math.round(intervalMs / 100) / 10}s, timeout ${timeoutSeconds}s.`);
+
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  for (;;) {
+    for (const name of WAIT_FILE_CANDIDATES) {
+      const value = readEnvKeyValue(resolve(projectDir, name));
+      if (value) {
+        log(`  Found PIEZAS_API_KEY in ${name}`);
+        return { value, file: name };
+      }
+    }
+    if (Date.now() >= deadline) {
+      log(`  No key file appeared within ${timeoutSeconds}s - continuing without a key.`);
+      return undefined;
+    }
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, intervalMs));
+  }
+}
+
+// resolveApiKey implements the key-intake precedence:
+// existing .env key > --key flag > process env > interactive prompt > --wait.
+// Only explicitly provided keys (--key/prompt/wait) may replace an existing
+// .env value; the process env never overrides an already-configured project.
+async function resolveApiKey(envPath, projectDir, options) {
+  const existingValue = readEnvKeyValue(envPath);
+  const flagKey = typeof options.key === 'string' && options.key.trim() ? options.key.trim() : undefined;
+
+  if (existingValue && !flagKey) {
+    return { key: existingValue, source: 'env-file' };
+  }
+  if (flagKey) {
+    return { key: flagKey, source: 'flag' };
+  }
+
+  const processKey = (options.env ?? process.env).PIEZAS_API_KEY;
+  if (processKey) {
+    return { key: processKey, source: 'process-env' };
+  }
+
+  if (options.interactive && !options.yes) {
+    const promptFn = options.promptFn ?? promptViaTerminal;
+    const answer = String((await promptFn(KEY_PROMPT)) ?? '').trim();
+    if (answer) {
+      return { key: answer, source: 'prompt' };
+    }
+  }
+
+  if (options.wait) {
+    const timeoutSeconds = options.waitTimeout ?? DEFAULT_WAIT_TIMEOUT_SECONDS;
+    const intervalMs = options.waitIntervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
+    const found = await waitForEnvKey(projectDir, timeoutSeconds, intervalMs);
+    if (found) {
+      return { key: found.value, source: 'wait', sourceFile: found.file };
+    }
+  }
+
+  // Nothing resolved: with a saved `piezas login` session (and a TTY or an
+  // explicit --from-login) create the app + mint a key via the platform.
+  const minted = await resolveKeyViaLogin(projectDir, options);
+  if (minted) {
+    return minted;
+  }
+
+  return { key: undefined, source: 'none' };
+}
+
+// --- Platform auth (piezas login / logout / whoami) ---------------------
+
+// resolveApiBase: --api-base flag > PIEZAS_API_BASE env > fallback (the
+// default recorded in piezas.manifest.json's apiBaseUrl).
+function resolveApiBase(options, env, fallback = DEFAULT_API_BASE_URL) {
+  const flagBase = typeof options.apiBase === 'string' && options.apiBase.trim()
+    ? options.apiBase.trim()
+    : undefined;
+  const envBase = typeof env.PIEZAS_API_BASE === 'string' && env.PIEZAS_API_BASE.trim()
+    ? env.PIEZAS_API_BASE.trim()
+    : undefined;
+  return (flagBase || envBase || fallback).replace(/\/+$/, '');
+}
+
+function adminBaseUrl(apiBase) {
+  return `${apiBase}${ADMIN_PATH_PREFIX}`;
+}
+
+// credentialsFilePath honors PIEZAS_HOME (used by tests) and defaults to
+// ~/.piezas/credentials.json.
+export function credentialsFilePath(env = process.env) {
+  const home = typeof env.PIEZAS_HOME === 'string' && env.PIEZAS_HOME.trim()
+    ? env.PIEZAS_HOME.trim()
+    : join(homedir(), '.piezas');
+  return join(home, 'credentials.json');
+}
+
+// readCredentials returns the stored CLI session or undefined. Corrupt or
+// token-less files read as "logged out" — never throw.
+function readCredentials(env = process.env) {
+  const filePath = credentialsFilePath(env);
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.cliToken !== 'string' || !parsed.cliToken) {
+      return undefined;
+    }
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeCredentials(credentials, env = process.env) {
+  const filePath = credentialsFilePath(env);
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  writeFileSync(filePath, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+  // writeFileSync's mode only applies on create — enforce on rewrite too.
+  chmodSync(filePath, 0o600);
+  return filePath;
+}
+
+// fetchJson: built-in fetch with a hard timeout and JSON parse guards.
+// Non-2xx statuses are returned (not thrown); network errors/timeouts throw.
+async function fetchJson(fetchFn, url, { method = 'GET', body, token, timeoutMs = HTTP_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = { accept: 'application/json' };
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    if (token) headers.authorization = `Bearer ${token}`;
+    const response = await fetchFn(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      data = undefined;
+    }
+    return { status: response.status, data };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// openInBrowser best-effort opens a URL. Failures are swallowed — the URL is
+// always printed, so the user can click/copy it manually.
+function openInBrowser(url) {
+  try {
+    const [command, args] = process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : ['xdg-open', [url]];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function printUserCode(userCode) {
+  const inner = `   ${userCode}   `;
+  const line = '─'.repeat(inner.length);
+  log(`      ╭${line}╮`);
+  log(`      │${inner}│`);
+  log(`      ╰${line}╯`);
+}
+
+const LOGIN_RETRY_HINT = 'Run `npx piezas login` to get a new code.';
+
+export async function login(options = {}) {
+  const previousEmit = emit;
+  if (options.json) {
+    emit = (message) => process.stderr.write(`${message}\n`);
+  }
+  let outcome;
+  try {
+    outcome = await runLogin(options);
+  } finally {
+    emit = previousEmit;
+  }
+  if (options.json) {
+    console.log(JSON.stringify(outcome.summary, null, 2));
+  }
+  return { exitCode: outcome.exitCode, ...outcome.summary };
+}
+
+async function runLogin(options) {
+  const env = options.env ?? process.env;
+  const fetchFn = options.fetchFn ?? fetch;
+  const apiBase = resolveApiBase(options, env);
+  const admin = adminBaseUrl(apiBase);
+
+  log('\n  🧱 Piezas login\n');
+
+  let start;
+  try {
+    start = await fetchJson(fetchFn, `${admin}/v1/portal/device-codes`, {
+      method: 'POST',
+      timeoutMs: options.httpTimeoutMs,
+    });
+  } catch (error) {
+    log(`  Could not reach ${apiBase} (${error?.message || 'network error'}). Check your connection and try again.`);
+    return { exitCode: 1, summary: { command: 'login', status: 'error', error: 'unreachable', apiBase } };
+  }
+
+  if (start.status === 429) {
+    log('  Too many sign-in requests are pending right now - wait a few minutes and try again.');
+    return { exitCode: 1, summary: { command: 'login', status: 'error', error: 'rate-limited', apiBase } };
+  }
+  const device = start.data;
+  if (start.status !== 201 || !device || typeof device.deviceCode !== 'string' || typeof device.userCode !== 'string') {
+    log(`  Sign-in could not be started (HTTP ${start.status}). Try again in a moment.`);
+    return { exitCode: 1, summary: { command: 'login', status: 'error', error: `http-${start.status}`, apiBase } };
+  }
+
+  const verificationUri = device.verificationUri || 'https://app.piezas.ai/device';
+  const confirmUrl = `${verificationUri}${verificationUri.includes('?') ? '&' : '?'}code=${encodeURIComponent(device.userCode)}`;
+
+  log('  Confirm this code in your browser to sign in:');
+  log('');
+  printUserCode(device.userCode);
+  log('');
+  log(`  ${confirmUrl}`);
+  log('');
+  const opener = options.openBrowserFn ?? openInBrowser;
+  if (opener(confirmUrl)) {
+    log('  Opening your browser... (if nothing happens, use the link above)');
+  }
+  log('  Waiting for approval...');
+
+  const intervalMs = options.pollIntervalMs
+    ?? (Number(device.interval) > 0 ? Number(device.interval) : 5) * 1000;
+  const lifetimeMs = (Number(device.expiresIn) > 0 ? Number(device.expiresIn) : 900) * 1000;
+  const deadline = Date.now() + lifetimeMs;
+
+  while (Date.now() < deadline) {
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, intervalMs));
+    let poll;
+    try {
+      poll = await fetchJson(fetchFn, `${admin}/v1/portal/device-codes/token`, {
+        method: 'POST',
+        body: { deviceCode: device.deviceCode },
+        timeoutMs: options.httpTimeoutMs,
+      });
+    } catch {
+      continue; // transient network trouble — keep polling until expiry
+    }
+
+    if (poll.status === 200 && poll.data?.status === 'ok' && typeof poll.data.cliToken === 'string') {
+      const credentials = {
+        cliToken: poll.data.cliToken,
+        tenantId: poll.data.tenantId,
+        tenantName: poll.data.tenantName,
+        email: poll.data.email,
+        apiBase,
+      };
+      const credentialsPath = writeCredentials(credentials, env);
+      log('');
+      log(`  Logged in as ${credentials.email}${credentials.tenantName ? ` (${credentials.tenantName})` : ''}.`);
+      log(`  Session saved to ${credentialsPath}`);
+      log('  Next: run `npx piezas init` in your project folder.\n');
+      return {
+        exitCode: 0,
+        summary: {
+          command: 'login',
+          status: 'ok',
+          tenantId: credentials.tenantId ?? null,
+          tenantName: credentials.tenantName ?? null,
+          email: credentials.email ?? null,
+          apiBase,
+          credentialsPath,
+        },
+      };
+    }
+    if (poll.status === 200) continue; // pending
+    if (poll.status === 404 || poll.status === 400) {
+      log(`  This sign-in code is no longer valid (expired or already used). ${LOGIN_RETRY_HINT}`);
+      return { exitCode: 1, summary: { command: 'login', status: 'expired', apiBase } };
+    }
+    // Any other status (e.g. a transient 5xx) — keep polling until expiry.
+  }
+
+  log(`  The sign-in code expired before it was approved. ${LOGIN_RETRY_HINT}`);
+  return { exitCode: 1, summary: { command: 'login', status: 'expired', apiBase } };
+}
+
+// How long logout waits for the server-side session revocation before giving
+// up and deleting the local credentials anyway.
+const LOGOUT_REVOKE_TIMEOUT_MS = 2000;
+
+export async function logout(options = {}) {
+  const env = options.env ?? process.env;
+  const credentialsPath = credentialsFilePath(env);
+  const credentials = readCredentials(env);
+
+  // Best-effort server-side revocation BEFORE deleting the local file: the
+  // 30-day cliToken is bound to a revocable server session, so logging out
+  // kills any copy of the token, not just this machine's file. Failures
+  // (offline, expired, 5xx, hung server) never block the local logout.
+  let revoked = false;
+  if (credentials?.cliToken) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const apiBase = resolveApiBase(options, env, credentials.apiBase || DEFAULT_API_BASE_URL);
+    try {
+      const response = await fetchJson(fetchFn, `${adminBaseUrl(apiBase)}/v1/portal/cli-sessions/revoke`, {
+        method: 'POST',
+        token: credentials.cliToken,
+        timeoutMs: options.revokeTimeoutMs ?? LOGOUT_REVOKE_TIMEOUT_MS,
+      });
+      revoked = response.status === 200;
+    } catch {
+      // ignore — logout is local-first
+    }
+  }
+
+  let removed = false;
+  if (existsSync(credentialsPath)) {
+    unlinkSync(credentialsPath);
+    removed = true;
+  }
+  const summary = { command: 'logout', removed, revoked, credentialsPath };
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(removed ? '  Logged out of Piezas.' : '  Not logged in - nothing to remove.');
+  }
+  return { exitCode: 0, ...summary };
+}
+
+export function whoami(options = {}) {
+  const env = options.env ?? process.env;
+  const credentials = readCredentials(env);
+  if (!credentials) {
+    if (options.json) {
+      console.log(JSON.stringify({ command: 'whoami', loggedIn: false }, null, 2));
+    } else {
+      console.log('  Not logged in. Run `npx piezas login` to sign in.');
+    }
+    return { exitCode: 1, command: 'whoami', loggedIn: false };
+  }
+
+  // Never include the cliToken here — whoami output is safe to paste anywhere.
+  const summary = {
+    command: 'whoami',
+    loggedIn: true,
+    tenantId: credentials.tenantId ?? null,
+    tenantName: credentials.tenantName ?? null,
+    email: credentials.email ?? null,
+    apiBase: credentials.apiBase ?? DEFAULT_API_BASE_URL,
+  };
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log('\n  🧱 Piezas CLI session\n');
+    console.log(`  Tenant: ${summary.tenantName ?? 'unknown'}${summary.tenantId ? ` (${summary.tenantId})` : ''}`);
+    console.log(`  Email:  ${summary.email ?? 'unknown'}`);
+    console.log(`  API:    ${summary.apiBase}\n`);
+  }
+  return { exitCode: 0, ...summary };
+}
+
+// slugifyAppName mirrors the Go control plane's slugify (and the dashboard
+// BFF): lowercase, [a-z0-9] runs joined by single hyphens, trimmed.
+function slugifyAppName(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// resolveKeyViaLogin: when no key was found by the normal intake chain but a
+// CLI session exists, create the app (or reuse it on a name conflict) and
+// mint a live key bound to it — the same composition the dashboard's
+// onboarding performs. Every failure degrades to "no key" with a friendly
+// message; init never crashes because of this step.
+async function resolveKeyViaLogin(projectDir, options) {
+  if (!options.fromLogin && !(options.interactive && !options.yes)) return undefined;
+  const env = options.env ?? process.env;
+  const credentials = readCredentials(env);
+  if (!credentials) return undefined;
+
+  const appName = (typeof options.app === 'string' && options.app.trim())
+    ? options.app.trim()
+    : basename(projectDir);
+
+  if (!options.fromLogin) {
+    const promptFn = options.promptFn ?? promptViaTerminal;
+    const answer = String(
+      (await promptFn(`You are signed in as ${credentials.email}. Create app "${appName}" and mint an API key now? [Y/n] `)) ?? '',
+    ).trim().toLowerCase();
+    if (answer === 'n' || answer === 'no') return undefined;
+  }
+
+  const fetchFn = options.fetchFn ?? fetch;
+  const apiBase = resolveApiBase(options, env, credentials.apiBase || DEFAULT_API_BASE_URL);
+  const admin = adminBaseUrl(apiBase);
+  const tenantPath = `${admin}/v1/tenants/${credentials.tenantId}`;
+  const httpOptions = { token: credentials.cliToken, timeoutMs: options.httpTimeoutMs };
+  const sessionExpired = () => {
+    log('  Your Piezas session has expired - run `npx piezas login`, then rerun init.');
+    return undefined;
+  };
+
+  try {
+    let app;
+    const created = await fetchJson(fetchFn, `${tenantPath}/partitions`, {
+      ...httpOptions,
+      method: 'POST',
+      body: { name: appName },
+    });
+    if (created.status === 201 && created.data?.id) {
+      app = created.data;
+      log(`  Created app "${app.name}"${credentials.tenantName ? ` in ${credentials.tenantName}` : ''}`);
+    } else if (created.status === 409) {
+      // The app already exists — find it by the same slug the platform
+      // derived (or by exact name) and reuse it, exactly like the dashboard.
+      const listed = await fetchJson(fetchFn, `${tenantPath}/partitions`, httpOptions);
+      if (listed.status === 401) return sessionExpired();
+      const slug = slugifyAppName(appName);
+      const existing = Array.isArray(listed.data?.data)
+        ? listed.data.data.find((p) => p?.slug === slug || p?.name === appName)
+        : undefined;
+      if (!existing) {
+        log('  An app with that name already exists but could not be found - continuing without a key.');
+        return undefined;
+      }
+      app = existing;
+      log(`  Reusing existing app "${app.name}"`);
+    } else if (created.status === 401) {
+      return sessionExpired();
+    } else {
+      log(`  Could not create the app (HTTP ${created.status}) - continuing without a key.`);
+      return undefined;
+    }
+
+    const minted = await fetchJson(fetchFn, `${tenantPath}/api-keys`, {
+      ...httpOptions,
+      method: 'POST',
+      body: { name: appName, environment: 'live', partitionId: app.id },
+    });
+    if (minted.status === 401) return sessionExpired();
+    if (minted.status !== 201 || typeof minted.data?.key !== 'string' || !minted.data.key) {
+      log(`  Could not mint an API key (HTTP ${minted.status}) - continuing without a key.`);
+      return undefined;
+    }
+    log(`  Minted a live API key for "${app.name}"`);
+    return { key: minted.data.key, source: 'login' };
+  } catch (error) {
+    log(`  Could not reach Piezas (${error?.message || 'network error'}) - continuing without a key.`);
+    return undefined;
+  }
+}
+
+// --- End platform auth ---------------------------------------------------
+
+function detectPackageManager(projectDir) {
+  if (existsSync(resolve(projectDir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(resolve(projectDir, 'yarn.lock'))) return 'yarn';
+  if (existsSync(resolve(projectDir, 'bun.lockb'))) return 'bun';
+  return 'npm';
+}
+
+// hasSdkDependency reports whether package.json already declares @piezas/sdk
+// (e.g. a `file:` tarball pin for testing a local build). Init must not clobber
+// such a pin by re-adding the published package from the registry.
+function hasSdkDependency(projectDir) {
+  const pkgJsonPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgJsonPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    return Boolean(
+      pkg?.dependencies?.['@piezas/sdk'] || pkg?.devDependencies?.['@piezas/sdk'],
+    );
+  } catch {
+    return false;
+  }
+}
+
+export async function init(options = {}) {
+  const previousEmit = emit;
+  if (options.json) {
+    emit = (message) => process.stderr.write(`${message}\n`);
+  }
+  let summary;
+  try {
+    summary = await runInit(options);
+  } finally {
+    emit = previousEmit;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  }
+  return { exitCode: 0, ...summary };
+}
+
+async function runInit(options) {
+  const currentDir = options.cwd || process.cwd();
+  const targetArg = options.targetArg;
+  const projectDir = targetArg && targetArg !== '.'
+    ? resolve(currentDir, targetArg)
+    : currentDir;
+  const deploymentMode = options.deploymentMode || DEFAULT_DEPLOYMENT_MODE;
+  const productType = options.productType || 'custom-app';
+  const mcpRequested = Boolean(options.mcp);
+  const appName = typeof options.app === 'string' && options.app.trim() ? options.app.trim() : undefined;
+
+  log('\n  🧱 Piezas by Softmax Data\n');
+
+  if (!existsSync(projectDir)) {
+    mkdirSync(projectDir, { recursive: true });
+    log(`  Created ${targetArg}`);
+  } else if (projectDir !== currentDir) {
+    log(`  Using ${targetArg}`);
+  }
+
+  ensurePackageJson(projectDir);
+
+  if (options.skipInstall) {
+    log('  Skipped @piezas/sdk install\n');
+  } else if (hasSdkDependency(projectDir)) {
+    log('  Preserving existing @piezas/sdk dependency (pin left untouched)\n');
+  } else {
+    log('  Installing @piezas/sdk...');
+    const pm = detectPackageManager(projectDir);
+    try {
+      execSync(`${pm} add @piezas/sdk`, { cwd: projectDir, stdio: 'pipe' });
+      log('  Installed @piezas/sdk\n');
+    } catch {
+      log('  Failed to install - run manually: npm install @piezas/sdk\n');
+    }
+  }
+
+  const manifestPath = resolve(projectDir, 'piezas.manifest.json');
+  const manifest = upsertManifest(manifestPath, {
+    deploymentMode,
+    productType,
+    recipes: options.recipes,
+    mcp: mcpRequested,
+    appName,
+  });
+
+  const piezasDir = resolve(projectDir, '.piezas');
+  mkdirSync(piezasDir, { recursive: true });
+  writeIfNew(
+    resolve(piezasDir, 'spec-builder.md'),
+    PIEZAS_SPEC_INSTRUCTIONS,
+    '.piezas/spec-builder.md (Piezas spec mode)',
+    { startMarker: PIEZAS_SPEC_START, appendIfNoMarker: false },
+  );
+
+  writeIfNew(resolve(projectDir, 'CLAUDE.md'), PIEZAS_INSTRUCTIONS, 'CLAUDE.md');
+
+  const commandsDir = resolve(projectDir, '.claude', 'commands');
+  mkdirSync(commandsDir, { recursive: true });
+  writeIfNew(
+    resolve(commandsDir, 'piezas.md'),
+    PIEZAS_INSTRUCTIONS,
+    '.claude/commands/piezas.md (Claude Code slash command)',
+  );
+  writeIfNew(
+    resolve(commandsDir, 'piezas-spec.md'),
+    PIEZAS_SPEC_INSTRUCTIONS,
+    '.claude/commands/piezas-spec.md (Claude Code spec command)',
+    { startMarker: PIEZAS_SPEC_START, appendIfNoMarker: false },
+  );
+
+  const cursorRulesPath = resolve(projectDir, '.cursor', 'rules', 'piezas.mdc');
+  mkdirSync(dirname(cursorRulesPath), { recursive: true });
+  writeIfNew(
+    cursorRulesPath,
+    `---\ndescription: Use Piezas backend APIs and SDK\nalwaysApply: true\n---\n\n${PIEZAS_INSTRUCTIONS}`,
+    '.cursor/rules/piezas.mdc',
+  );
+  writeIfNew(resolve(projectDir, '.cursorrules'), PIEZAS_INSTRUCTIONS, '.cursorrules');
+
+  writeIfNew(resolve(projectDir, 'AGENTS.md'), `# Project Instructions\n\n${PIEZAS_INSTRUCTIONS}`, 'AGENTS.md');
+  writeIfNew(resolve(projectDir, '.windsurfrules'), PIEZAS_INSTRUCTIONS, '.windsurfrules');
+  const mcpScaffold = scaffoldMcpRoute(projectDir, deploymentMode, mcpRequested);
+
+  const gitignoreUpdated = ensureGitignore(projectDir);
+
+  const envPath = resolve(projectDir, '.env');
+  const resolved = await resolveApiKey(envPath, projectDir, options);
+  let apiKeyStatus = 'missing';
+  let keyFormatWarning = false;
+  if (resolved.key) {
+    if (!API_KEY_FORMAT.test(resolved.key)) {
+      keyFormatWarning = true;
+      log('  Warning: the key does not look like sk_live_... / sk_test_... - using it anyway.');
+    }
+    const action = writeEnvKey(envPath, resolved.key);
+    apiKeyStatus = action === 'kept' ? 'configured' : 'written';
+    if (action === 'created') log('  Created .env with PIEZAS_API_KEY');
+    if (action === 'appended') log('  Added PIEZAS_API_KEY to .env');
+    if (action === 'replaced') log('  Replaced PIEZAS_API_KEY in .env');
+    // A --wait drop file other than .env itself is a transfer vehicle holding
+    // the secret un-gitignored — remove it once the key lives in .env.
+    if (resolved.sourceFile && resolved.sourceFile !== '.env') {
+      try {
+        unlinkSync(resolve(projectDir, resolved.sourceFile));
+        log(`  Removed ${resolved.sourceFile} (key moved to .env)`);
+      } catch {
+        log(`  Warning: could not remove ${resolved.sourceFile} - delete it yourself; it contains your key and is not git-ignored.`);
+      }
+    }
+  }
+
+  log('\n  Done! Your project is set up for Piezas.\n');
+  log('  Your AI coding agent now knows how to use Piezas:');
+  log('    Claude Code  -> /piezas or reads CLAUDE.md automatically');
+  log('    Spec mode    -> /piezas-spec in Claude Code, or ask Cursor/Codex to run Piezas spec mode');
+  log('    Cursor       -> reads .cursor/rules/piezas.mdc automatically');
+  log('    Codex        -> reads AGENTS.md automatically');
+  log('    Windsurf     -> reads .windsurfrules automatically');
+  log('');
+  if (apiKeyStatus === 'missing') {
+    log('  apiKey: missing');
+    log(`  Put PIEZAS_API_KEY=<your key> in ${envPath} (dashboard -> API Keys -> "Download .env"), or rerun: npx piezas init --key <key>`);
+    log('  No account key handy? Run `npx piezas login`, then `npx piezas init --from-login` to create an app + key from the terminal.');
+  } else if (apiKeyStatus === 'configured') {
+    log(`  apiKey: configured (already in ${envPath})`);
+  } else {
+    log(`  apiKey: written to ${envPath}`);
+  }
+  log('');
+  log('  Next steps:');
+  let step = 1;
+  if (apiKeyStatus === 'missing') {
+    log(`  ${step++}. Get an API key at https://app.piezas.ai (dashboard -> API Keys)`);
+    log(`  ${step++}. Add PIEZAS_API_KEY=sk_live_xxx to .env (server-side only)`);
+  }
+  log(`  ${step++}. Run /piezas-spec [idea] or ask for Piezas spec mode`);
+  log(`  ${step++}. After the spec is written, tell your AI agent to code from SPEC.md`);
+  log(`  ${step++}. Run npx piezas doctor after generated changes\n`);
+  if (mcpScaffold.enabled) {
+    log(`  MCP route: ${mcpScaffold.routePath} (protect with app auth before public use)\n`);
+  }
+
+  return {
+    command: 'init',
+    projectDir,
+    apiKey: apiKeyStatus,
+    apiKeySource: resolved.source,
+    envPath,
+    gitignoreUpdated,
+    cursorRulesPath,
+    appName: manifest?.appName ?? appName ?? null,
+    apiBaseUrl: manifest?.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+    manifestPath,
+    keyFormatWarning,
+  };
+}
+
+function readJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+function lineNumber(content, index) {
+  if (index < 0) return undefined;
+  return content.slice(0, index).split('\n').length;
+}
+
+function addFinding(findings, severity, code, message, file, line) {
+  findings.push({ severity, code, message, file, line });
+}
+
+function isTextFile(filePath) {
+  const name = basename(filePath);
+  return (
+    TEXT_EXTENSIONS.has(extname(filePath)) ||
+    name.startsWith('.env') ||
+    name === '.gitignore' ||
+    name === '.cursorrules' ||
+    name === '.windsurfrules'
+  );
+}
+
+function isCodeFile(filePath) {
+  return CODE_EXTENSIONS.has(extname(filePath));
+}
+
+function listFiles(projectDir) {
+  const files = [];
+
+  function walk(dir) {
+    for (const entry of readdirSync(dir)) {
+      if (DEFAULT_EXCLUDED_DIRS.has(entry)) {
+        continue;
+      }
+
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      } else if (stat.isFile() && isTextFile(fullPath)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(projectDir);
+  return files;
+}
+
+function normalizeRel(projectDir, filePath) {
+  return relative(projectDir, filePath).replaceAll('\\', '/');
+}
+
+function loadManifest(projectDir, findings) {
+  const manifestPath = resolve(projectDir, 'piezas.manifest.json');
+  if (!existsSync(manifestPath)) {
+    addFinding(
+      findings,
+      'warn',
+      'PZ000',
+      'Missing piezas.manifest.json. Run `npx piezas init` so agents and doctor share a source of truth.',
+    );
+    return {
+      exists: false,
+      path: manifestPath,
+      manifest: buildDefaultManifest({ deploymentMode: 'unknown' }),
+    };
+  }
+
+  try {
+    return {
+      exists: true,
+      path: manifestPath,
+      manifest: readJsonFile(manifestPath),
+    };
+  } catch (error) {
+    addFinding(
+      findings,
+      'error',
+      'PZ000',
+      `piezas.manifest.json is not valid JSON: ${error.message}`,
+      'piezas.manifest.json',
+    );
+    return {
+      exists: false,
+      path: manifestPath,
+      manifest: buildDefaultManifest({ deploymentMode: 'unknown' }),
+    };
+  }
+}
+
+function packageJson(projectDir) {
+  const packagePath = resolve(projectDir, 'package.json');
+  if (!existsSync(packagePath)) return undefined;
+  try {
+    return readJsonFile(packagePath);
+  } catch {
+    return undefined;
+  }
+}
+
+function hasServerRuntimeArtifact(rel, content) {
+  return (
+    /^app\/api\/.+\/route\.[cm]?[tj]sx?$/.test(rel) ||
+    /^pages\/api\//.test(rel) ||
+    /(^|\/)middleware\.[cm]?[tj]s$/.test(rel) ||
+    /['"]use server['"]/.test(content)
+  );
+}
+
+function hasClientDirective(content) {
+  return /^\s*['"]use client['"]/.test(content);
+}
+
+function scanSecretExposure(projectDir, files, findings) {
+  for (const filePath of files) {
+    const rel = normalizeRel(projectDir, filePath);
+    if (!isCodeFile(filePath) && !basename(rel).startsWith('.env')) continue;
+    const content = readFileSync(filePath, 'utf-8');
+    const nextPublicIndex = content.indexOf('NEXT_PUBLIC_PIEZAS_API_KEY');
+    if (nextPublicIndex >= 0) {
+      addFinding(
+        findings,
+        'error',
+        'PZ001',
+        'PIEZAS_API_KEY must never use a NEXT_PUBLIC_ prefix.',
+        rel,
+        lineNumber(content, nextPublicIndex),
+      );
+    }
+
+    if (hasClientDirective(content)) {
+      for (const secret of ['PIEZAS_API_KEY', 'ADMIN_PASS', 'ADMIN_TOKEN', 'GOOGLE_CLIENT_SECRET', 'ZOOM_CLIENT_SECRET']) {
+        const secretIndex = content.indexOf(secret);
+        if (secretIndex >= 0) {
+          addFinding(
+            findings,
+            'error',
+            'PZ001',
+            `${secret} is referenced from a client component. Keep secrets server-side only.`,
+            rel,
+            lineNumber(content, secretIndex),
+          );
+        }
+      }
+    }
+
+    if (basename(rel).startsWith('.env') && content.includes('PIEZAS_API_KEY=')) {
+      const gitignorePath = resolve(projectDir, '.gitignore');
+      const gitignore = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+      if (!/(^|\n)\.env(\n|$)|(^|\n)\.env\*/.test(gitignore)) {
+        addFinding(
+          findings,
+          'warn',
+          'PZ001',
+          '.env contains PIEZAS_API_KEY but .gitignore does not clearly ignore .env files.',
+          rel,
+        );
+      }
+    }
+  }
+}
+
+function scanDeploymentMode(projectDir, files, manifest, findings) {
+  if (manifest.deploymentMode !== 'static') {
+    return;
+  }
+
+  for (const filePath of files) {
+    if (!isCodeFile(filePath)) continue;
+    const rel = normalizeRel(projectDir, filePath);
+    const content = readFileSync(filePath, 'utf-8');
+    if (hasServerRuntimeArtifact(rel, content)) {
+      addFinding(
+        findings,
+        'error',
+        'PZ002',
+        'Static deployment mode cannot use API routes, middleware, or server actions.',
+        rel,
+      );
+    }
+    if (content.includes('PIEZAS_API_KEY') || content.includes('ADMIN_PASS') || content.includes('ADMIN_TOKEN')) {
+      addFinding(
+        findings,
+        'error',
+        'PZ002',
+        'Static deployment mode cannot use server-only secrets in deployed app code.',
+        rel,
+      );
+    }
+  }
+}
+
+function scanLocalDatabase(projectDir, files, findings) {
+  const pkg = packageJson(projectDir);
+  const deps = {
+    ...(pkg?.dependencies || {}),
+    ...(pkg?.devDependencies || {}),
+  };
+  for (const packageName of LOCAL_DB_PACKAGES) {
+    if (deps[packageName]) {
+      addFinding(
+        findings,
+        'warn',
+        'PZ003',
+        `Detected ${packageName}. Do not create local database tables for Piezas-backed business records.`,
+        'package.json',
+      );
+    }
+  }
+
+  for (const filePath of files) {
+    const rel = normalizeRel(projectDir, filePath);
+    if (/(^|\/)(schema\.prisma|drizzle\.config\.)/.test(rel)) {
+      addFinding(
+        findings,
+        'warn',
+        'PZ003',
+        'Detected local database schema/config. Confirm this is not duplicating Piezas-owned data.',
+        rel,
+      );
+    }
+  }
+}
+
+function scanOAuthTokenStorage(projectDir, files, findings) {
+  const tokenPattern = /\b(access_token|refresh_token|oauth_token|id_token)\b/i;
+  for (const filePath of files) {
+    if (!isCodeFile(filePath)) continue;
+    const rel = normalizeRel(projectDir, filePath);
+    if (rel.includes('.test.')) continue;
+    const content = readFileSync(filePath, 'utf-8');
+    const match = tokenPattern.exec(content);
+    if (match) {
+      addFinding(
+        findings,
+        'warn',
+        'PZ004',
+        'OAuth tokens should live in Piezas Integrations, not app storage or app database records.',
+        rel,
+        lineNumber(content, match.index),
+      );
+    }
+  }
+}
+
+function scanAdminTokenInUrl(projectDir, files, findings) {
+  for (const filePath of files) {
+    if (!isCodeFile(filePath)) continue;
+    const rel = normalizeRel(projectDir, filePath);
+    const content = readFileSync(filePath, 'utf-8');
+    const hasTokenQuery =
+      /searchParams[\s\S]{0,300}\btoken\b/.test(content) ||
+      /\?token=/.test(content) ||
+      /method=["']get["'][\s\S]{0,300}name=["']token["']/.test(content);
+    const hasAdminContext =
+      /ADMIN_TOKEN|ADMIN_PASS|getOptionalAdminToken|admin token|Admin token/i.test(content) ||
+      /(^|\/)admin(\/|$)/.test(rel);
+
+    if (hasTokenQuery && hasAdminContext) {
+      addFinding(
+        findings,
+        'error',
+        'PZ005',
+        'Do not put admin tokens/passwords in query params. Use a POST login and HTTP-only session cookie or an auth role.',
+        rel,
+        lineNumber(content, content.indexOf('searchParams')),
+      );
+    }
+  }
+}
+
+function scanHiddenTimeTrust(projectDir, files, findings) {
+  for (const filePath of files) {
+    if (!isCodeFile(filePath)) continue;
+    const rel = normalizeRel(projectDir, filePath);
+    const content = readFileSync(filePath, 'utf-8');
+    if (!/name=["']startTime["']/.test(content) || !/type=["']hidden["']/.test(content)) continue;
+    if (!/formData\.get\(["']startTime["']\)/.test(content)) continue;
+    if (!/create(Public)?Booking|book(ing)?/i.test(content)) continue;
+
+    const serverActionIndex = content.search(/['"]use server['"]/);
+    const serverActionBody = serverActionIndex >= 0 ? content.slice(serverActionIndex) : content;
+    if (!/listAvailableSlots|isSlotAvailable|validate.*Slot|revalidate.*Slot/i.test(serverActionBody)) {
+      addFinding(
+        findings,
+        'error',
+        'PZ006',
+        'Public booking flow appears to trust a hidden startTime. Re-fetch availability and validate the slot server-side before booking.',
+        rel,
+        lineNumber(content, content.indexOf('startTime')),
+      );
+    }
+  }
+}
+
+function dynamicParamsFromPath(rel) {
+  const params = [];
+  const pattern = /\[([A-Za-z0-9_]+)\]/g;
+  let match = pattern.exec(rel);
+  while (match) {
+    params.push(match[1]);
+    match = pattern.exec(rel);
+  }
+  return params;
+}
+
+function scanUnusedDynamicRoutes(projectDir, files, findings) {
+  for (const filePath of files) {
+    const rel = normalizeRel(projectDir, filePath);
+    if (!/(^|\/)(page|route)\.[cm]?[tj]sx?$/.test(rel)) continue;
+    const params = dynamicParamsFromPath(rel);
+    if (params.length === 0) continue;
+
+    const content = readFileSync(filePath, 'utf-8');
+    for (const param of params) {
+      const uses = content.match(new RegExp(`\\b${param}\\b`, 'g')) || [];
+      if (uses.length <= 1) {
+        addFinding(
+          findings,
+          'warn',
+          'PZ007',
+          `Dynamic route param [${param}] appears unused. Public routes should use all identity/scope params to avoid collisions.`,
+          rel,
+        );
+      }
+    }
+  }
+}
+
+function scanIntegrationActions(projectDir, files, findings) {
+  const actionPattern = /['"](?:google_calendar|zoom|hubspot|salesforce|slack|gmail)\.[A-Za-z0-9_.-]+['"]/g;
+  for (const filePath of files) {
+    if (!isCodeFile(filePath)) continue;
+    const rel = normalizeRel(projectDir, filePath);
+    if (rel.includes('.test.')) continue;
+    const content = readFileSync(filePath, 'utf-8');
+    const actions = content.match(actionPattern);
+    if (!actions) continue;
+
+    if (!/connector\.actions|connectors\.[A-Za-z0-9_]*actions|\.actions\b|capabilities/i.test(content)) {
+      addFinding(
+        findings,
+        'warn',
+        'PZ008',
+        'Hardcoded integration action IDs found without checking connector action metadata first.',
+        rel,
+        lineNumber(content, content.indexOf(actions[0].slice(1, -1))),
+      );
+    }
+  }
+}
+
+function projectHasServerRisk(projectDir, files) {
+  return files.some((filePath) => {
+    const rel = normalizeRel(projectDir, filePath);
+    const content = readFileSync(filePath, 'utf-8');
+    return hasServerRuntimeArtifact(rel, content);
+  });
+}
+
+function scanCoverageConfig(projectDir, files, findings) {
+  const vitestConfig = files.find((filePath) => /(^|\/)vitest\.config\.[cm]?[tj]s$/.test(normalizeRel(projectDir, filePath)));
+  if (!vitestConfig || !projectHasServerRisk(projectDir, files)) return;
+
+  const rel = normalizeRel(projectDir, vitestConfig);
+  const content = readFileSync(vitestConfig, 'utf-8');
+  if (/coverage\s*:\s*\{[\s\S]*include\s*:/.test(content) && !/['"`](src\/)?app\/|['"`]app\/|route\.[cm]?[tj]s/.test(content)) {
+    addFinding(
+      findings,
+      'warn',
+      'PZ009',
+      'Coverage include list appears to exclude app/API/server-action code. Coverage may look high while risky routes remain untested.',
+      rel,
+      lineNumber(content, content.indexOf('include')),
+    );
+  }
+}
+
+function scanPackageScripts(projectDir, findings) {
+  const pkg = packageJson(projectDir);
+  if (!pkg) return;
+  const nextVersion = pkg.dependencies?.next || pkg.devDependencies?.next;
+  const major = Number(String(nextVersion || '').replace(/^[^0-9]*/, '').split('.')[0]);
+  if (major >= 16 && pkg.scripts?.lint?.includes('next lint')) {
+    addFinding(
+      findings,
+      'warn',
+      'PZ010',
+      '`next lint` is not reliable with this Next.js version. Use ESLint directly or update the lint script.',
+      'package.json',
+    );
+  }
+}
+
+export function runDoctor(projectDir, options = {}) {
+  const resolvedDir = resolve(projectDir);
+  const findings = [];
+  const manifestInfo = loadManifest(resolvedDir, findings);
+  const files = existsSync(resolvedDir) ? listFiles(resolvedDir) : [];
+
+  scanSecretExposure(resolvedDir, files, findings);
+  scanDeploymentMode(resolvedDir, files, manifestInfo.manifest, findings);
+  scanLocalDatabase(resolvedDir, files, findings);
+  scanOAuthTokenStorage(resolvedDir, files, findings);
+  scanAdminTokenInUrl(resolvedDir, files, findings);
+  scanHiddenTimeTrust(resolvedDir, files, findings);
+  scanUnusedDynamicRoutes(resolvedDir, files, findings);
+  scanIntegrationActions(resolvedDir, files, findings);
+  scanCoverageConfig(resolvedDir, files, findings);
+  scanPackageScripts(resolvedDir, findings);
+
+  const errors = findings.filter((finding) => finding.severity === 'error').length;
+  const warnings = findings.filter((finding) => finding.severity === 'warn').length;
+
+  return {
+    projectDir: resolvedDir,
+    manifest: manifestInfo.manifest,
+    manifestFound: manifestInfo.exists,
+    findings,
+    errors,
+    warnings,
+    passed: errors === 0 && (!options.strict || warnings === 0),
+  };
+}
+
+export function formatDoctorResult(result) {
+  const lines = [
+    '',
+    '  🧱 Piezas Doctor',
+    '',
+    `  Project: ${result.projectDir}`,
+    `  Manifest: ${result.manifestFound ? 'found' : 'missing'}`,
+    `  Deployment mode: ${result.manifest.deploymentMode || 'unknown'}`,
+    '',
+  ];
+
+  if (result.findings.length === 0) {
+    lines.push('  No issues found.');
+  } else {
+    for (const finding of result.findings) {
+      const marker = finding.severity === 'error' ? 'ERROR' : 'WARN ';
+      const location = finding.file
+        ? ` (${finding.file}${finding.line ? `:${finding.line}` : ''})`
+        : '';
+      lines.push(`  ${marker} ${finding.code}${location}`);
+      lines.push(`        ${finding.message}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(`  Summary: ${result.errors} error(s), ${result.warnings} warning(s)`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function help() {
+  console.log('\n  🧱 Piezas CLI\n');
+  console.log('  Usage:');
+  console.log('    npx piezas init [dir]            Set up Piezas in a project');
+  console.log('    npx piezas login                 Sign in via your browser (device code)');
+  console.log('    npx piezas logout                Remove the saved CLI session');
+  console.log('    npx piezas whoami                Show which account the CLI is signed in as');
+  console.log('    npx piezas doctor [dir]          Scan generated app guardrails\n');
+  console.log('  Init options:');
+  console.log('    --key <sk_live_...>              API key to save into .env as PIEZAS_API_KEY');
+  console.log('    --wait                           Watch the folder for a downloaded .env (.env / .env.download / env.txt)');
+  console.log('    --wait-timeout <seconds>         How long --wait polls before giving up (default 300)');
+  console.log('    --app <name>                     App name recorded in piezas.manifest.json (and used for auto-created apps)');
+  console.log('    --from-login                     When no key is found, create an app + key with your saved login');
+  console.log('    --yes                            Non-interactive: never prompt (for agents/CI)');
+  console.log('    --json                           Print a machine-readable JSON summary');
+  console.log('    --mode next-bff|static|server-runtime|custom-backend');
+  console.log('    --product-type custom-app|crm-intake|booking-site|...');
+  console.log('    --recipe booking-site|crm-project-finance|client-services-os');
+  console.log('    --recipe can be repeated or comma-separated');
+  console.log('    --mcp                            Scaffold an SDK-backed MCP route for server modes');
+  console.log('    --skip-install                   Do not install @piezas/sdk (alias: --no-deps)\n');
+  console.log('  Login options:');
+  console.log('    --api-base <url>                 Piezas API base URL (default https://api.piezas.ai; also PIEZAS_API_BASE)');
+  console.log('    --json                           Print a machine-readable JSON summary\n');
+  console.log('  logout / whoami options:');
+  console.log('    --json                           Print machine-readable JSON\n');
+  console.log('  Doctor options:');
+  console.log('    --strict                         Treat warnings as failures');
+  console.log('    --json                           Print machine-readable JSON\n');
+  console.log('  Exit codes: 0 success, 1 failure, 2 usage error\n');
+}
+
+const INIT_FLAG_KEYS = new Set([
+  'apiBase',
+  'app',
+  'fromLogin',
+  'json',
+  'key',
+  'mcp',
+  'mode',
+  'noDeps',
+  'productType',
+  'recipe',
+  'recipes',
+  'skipDeps',
+  'skipInstall',
+  'wait',
+  'waitTimeout',
+  'yes',
+]);
+const DOCTOR_FLAG_KEYS = new Set(['json', 'strict']);
+const LOGIN_FLAG_KEYS = new Set(['apiBase', 'json']);
+const SESSION_FLAG_KEYS = new Set(['json']);
+
+function kebabCase(flagKey) {
+  return flagKey.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+}
+
+function usageError(message) {
+  console.error(`  Error: ${message}`);
+  console.error('  Run `npx piezas` for usage.');
+  return 2;
+}
+
+function lastValue(value) {
+  return Array.isArray(value) ? value[value.length - 1] : value;
+}
+
+function rejectUnknownFlags(flags, allowed, command) {
+  for (const key of Object.keys(flags)) {
+    if (!allowed.has(key)) {
+      return usageError(`unknown flag --${kebabCase(key)} for ${command}`);
+    }
+  }
+  return undefined;
+}
+
+export async function main(argv = process.argv, currentDir = process.cwd()) {
+  const command = argv[2];
+  const { flags, positional } = parseCliArgs(argv.slice(3));
+
+  if (command === 'init') {
+    const unknown = rejectUnknownFlags(flags, INIT_FLAG_KEYS, 'init');
+    if (unknown !== undefined) return unknown;
+    if (flags.wait && flags.key) {
+      return usageError('--wait cannot be combined with --key');
+    }
+    if (flags.key !== undefined && typeof lastValue(flags.key) !== 'string') {
+      return usageError('--key requires a value');
+    }
+    if (flags.app !== undefined && typeof lastValue(flags.app) !== 'string') {
+      return usageError('--app requires a value');
+    }
+    let waitTimeout;
+    if (flags.waitTimeout !== undefined) {
+      waitTimeout = Number(lastValue(flags.waitTimeout));
+      if (!Number.isFinite(waitTimeout) || waitTimeout <= 0) {
+        return usageError('--wait-timeout requires a positive number of seconds');
+      }
+    }
+
+    const json = Boolean(flags.json);
+    const yes = Boolean(flags.yes);
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !yes && !json;
+
+    try {
+      const result = await init({
+        cwd: currentDir,
+        targetArg: positional[0],
+        deploymentMode: lastValue(flags.mode),
+        productType: lastValue(flags.productType),
+        recipes: flags.recipe ?? flags.recipes,
+        mcp: Boolean(flags.mcp),
+        skipInstall: Boolean(flags.skipInstall || flags.noDeps || flags.skipDeps),
+        key: lastValue(flags.key),
+        app: lastValue(flags.app),
+        apiBase: lastValue(flags.apiBase),
+        fromLogin: Boolean(flags.fromLogin),
+        wait: Boolean(flags.wait),
+        waitTimeout,
+        yes,
+        json,
+        interactive,
+      });
+      return result.exitCode ?? 0;
+    } catch (error) {
+      console.error(`  Error: ${error?.message || error}`);
+      return 1;
+    }
+  }
+
+  if (command === 'login') {
+    const unknown = rejectUnknownFlags(flags, LOGIN_FLAG_KEYS, 'login');
+    if (unknown !== undefined) return unknown;
+    if (flags.apiBase !== undefined && typeof lastValue(flags.apiBase) !== 'string') {
+      return usageError('--api-base requires a value');
+    }
+    try {
+      const result = await login({
+        apiBase: lastValue(flags.apiBase),
+        json: Boolean(flags.json),
+      });
+      return result.exitCode;
+    } catch (error) {
+      console.error(`  Error: ${error?.message || error}`);
+      return 1;
+    }
+  }
+
+  if (command === 'logout') {
+    const unknown = rejectUnknownFlags(flags, SESSION_FLAG_KEYS, 'logout');
+    if (unknown !== undefined) return unknown;
+    try {
+      return (await logout({ json: Boolean(flags.json) })).exitCode;
+    } catch (error) {
+      console.error(`  Error: ${error?.message || error}`);
+      return 1;
+    }
+  }
+
+  if (command === 'whoami') {
+    const unknown = rejectUnknownFlags(flags, SESSION_FLAG_KEYS, 'whoami');
+    if (unknown !== undefined) return unknown;
+    try {
+      return whoami({ json: Boolean(flags.json) }).exitCode;
+    } catch (error) {
+      console.error(`  Error: ${error?.message || error}`);
+      return 1;
+    }
+  }
+
+  if (command === 'doctor') {
+    const unknown = rejectUnknownFlags(flags, DOCTOR_FLAG_KEYS, 'doctor');
+    if (unknown !== undefined) return unknown;
+    const projectDir = positional[0] ? resolve(currentDir, positional[0]) : currentDir;
+    const result = runDoctor(projectDir, { strict: Boolean(flags.strict) });
+    if (flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatDoctorResult(result));
+    }
+    return result.passed ? 0 : 1;
+  }
+
+  if (command) {
+    return usageError(`unknown command '${command}'`);
+  }
+  help();
+  return 0;
+}
+
+function isCliEntrypoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}
+
+if (isCliEntrypoint()) {
+  main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      console.error(`  Error: ${error?.message || error}`);
+      process.exitCode = 1;
+    },
+  );
+}