@distributionos/cli 0.1.0

package/src/detect.js

@@ -0,0 +1,279 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { groupRoutesByPrivacy } from './privacy.js';
+
+const execFileAsync = promisify(execFile);
+
+const SKIP_DIRS = new Set([
+  '.git',
+  '.next',
+  '.turbo',
+  '.vercel',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+]);
+
+const SKIP_FILE_PATTERNS = [
+  /(^|\/)\.env($|\.)/i,
+  /(^|\/)id_rsa($|\.)/i,
+  /(^|\/)id_dsa($|\.)/i,
+  /(^|\/)id_ecdsa($|\.)/i,
+  /(^|\/)id_ed25519($|\.)/i,
+  /(^|\/)[^/]*(secret|secrets|credential|credentials|private-key|private_key|service-account|serviceAccount|token|tokens)[^/]*$/i,
+  /\.(pem|key|p12|pfx)$/i,
+];
+
+const INSTRUCTION_FILE_CANDIDATES = [
+  { path: 'AGENTS.md', priority: 1 },
+  { path: 'CLAUDE.md', priority: 2 },
+  { path: '.cursor/rules/distributionos.md', priority: 3 },
+  { path: '.cursorrules', priority: 4 },
+  { path: 'DEVIN.md', priority: 5 },
+];
+
+export async function scanRepo(cwd) {
+  const [packageJson, files, git] = await Promise.all([
+    readPackageJson(cwd),
+    listFiles(cwd),
+    detectGitState(cwd),
+  ]);
+  const framework = detectFramework({ files, packageJson });
+  const packageManager = detectPackageManager(files);
+  const routes = detectRoutes(files);
+
+  return {
+    cwd,
+    packageJson,
+    files,
+    git,
+    framework,
+    packageManager,
+    commands: detectCommands(packageJson, packageManager),
+    routes,
+    routePrivacy: groupRoutesByPrivacy(routes),
+    layoutCandidates: detectLayoutCandidates(files),
+    instructionFiles: await readInstructionFiles(cwd),
+    contentFiles: detectContentFiles(files),
+    deployHints: detectDeployHints(files, packageJson),
+  };
+}
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readPackageJson(cwd) {
+  const filePath = path.join(cwd, 'package.json');
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function detectPackageManager(files) {
+  const fileSet = new Set(files);
+  if (fileSet.has('pnpm-lock.yaml')) return 'pnpm';
+  if (fileSet.has('yarn.lock')) return 'yarn';
+  if (fileSet.has('bun.lockb') || fileSet.has('bun.lock')) return 'bun';
+  if (fileSet.has('package-lock.json')) return 'npm';
+  return 'unknown';
+}
+
+function detectFramework({ files, packageJson }) {
+  const deps = {
+    ...(packageJson?.dependencies ?? {}),
+    ...(packageJson?.devDependencies ?? {}),
+  };
+  const fileSet = new Set(files);
+  if (deps.next || fileSet.has('next.config.ts') || fileSet.has('next.config.js')) {
+    return 'next';
+  }
+  if (deps.vite || fileSet.has('vite.config.ts') || fileSet.has('vite.config.js')) {
+    return deps.react || deps['@vitejs/plugin-react'] ? 'vite-react' : 'vite';
+  }
+  if (deps['react-scripts']) return 'create-react-app';
+  if (deps.react) return 'react';
+  return 'unknown';
+}
+
+function detectCommands(packageJson, packageManager) {
+  const scripts = packageJson?.scripts ?? {};
+  const run = commandName => packageManager === 'unknown'
+    ? `npm run ${commandName}`
+    : `${packageManager} run ${commandName}`;
+
+  return {
+    build: scripts.build ? run('build') : null,
+    test: scripts.test ? run('test') : null,
+    lint: scripts.lint ? run('lint') : null,
+  };
+}
+
+async function detectGitState(cwd) {
+  try {
+    const [{ stdout: root }, { stdout: status }, branchResult] = await Promise.all([
+      execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd, timeout: 5000 }),
+      execFileAsync('git', ['status', '--short'], { cwd, timeout: 5000 }),
+      execFileAsync('git', ['branch', '--show-current'], { cwd, timeout: 5000 }).catch(() => ({ stdout: '' })),
+    ]);
+    const lines = status.split(/\r?\n/).map(line => line.trimEnd()).filter(Boolean);
+    return {
+      isGitRepo: true,
+      root: root.trim(),
+      branch: branchResult.stdout.trim() || null,
+      dirty: lines.length > 0,
+      statusLines: lines,
+    };
+  } catch {
+    return {
+      isGitRepo: false,
+      root: null,
+      branch: null,
+      dirty: false,
+      statusLines: [],
+    };
+  }
+}
+
+async function listFiles(cwd, maxFiles = 4000) {
+  const results = [];
+
+  async function walk(relativeDir) {
+    if (results.length >= maxFiles) return;
+    const absoluteDir = path.join(cwd, relativeDir);
+    let entries = [];
+    try {
+      entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (results.length >= maxFiles) return;
+      const relativePath = toPosix(path.join(relativeDir, entry.name));
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) await walk(relativePath);
+      } else if (entry.isFile() && !shouldSkipFile(relativePath)) {
+        results.push(relativePath);
+      }
+    }
+  }
+
+  await walk('');
+  return results.sort();
+}
+
+function shouldSkipFile(relativePath) {
+  const normalized = toPosix(relativePath);
+  return SKIP_FILE_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function detectRoutes(files) {
+  const routes = new Set();
+  for (const file of files) {
+    const appRoute = routeFromAppRouterFile(file);
+    if (appRoute) routes.add(appRoute);
+
+    const pageRoute = routeFromPagesRouterFile(file);
+    if (pageRoute) routes.add(pageRoute);
+  }
+  return [...routes].sort(routeSort);
+}
+
+function routeFromAppRouterFile(file) {
+  if (!/(^|\/)page\.(jsx?|tsx?|mdx)$/.test(file)) return null;
+  const parts = file.split('/');
+  const appIndex = parts[0] === 'app' ? 0 : parts[0] === 'src' && parts[1] === 'app' ? 1 : -1;
+  if (appIndex < 0) return null;
+
+  const routeParts = parts
+    .slice(appIndex + 1, -1)
+    .filter(segment => segment && !segment.startsWith('(') && !segment.startsWith('@'));
+  if (routeParts[0] === 'api') return null;
+  return routeParts.length ? `/${routeParts.join('/')}` : '/';
+}
+
+function routeFromPagesRouterFile(file) {
+  if (!/(^|\/)[^/]+\.(jsx?|tsx?|mdx)$/.test(file)) return null;
+  const parts = file.split('/');
+  const pagesIndex = parts[0] === 'pages' ? 0 : parts[0] === 'src' && parts[1] === 'pages' ? 1 : -1;
+  if (pagesIndex < 0) return null;
+
+  const routeParts = parts.slice(pagesIndex + 1);
+  if (routeParts[0] === 'api') return null;
+  const last = routeParts[routeParts.length - 1].replace(/\.(jsx?|tsx?|mdx)$/, '');
+  routeParts[routeParts.length - 1] = last;
+  if (routeParts[0]?.startsWith('_')) return null;
+  const cleaned = routeParts.filter(segment => segment !== 'index');
+  return cleaned.length ? `/${cleaned.join('/')}` : '/';
+}
+
+function detectLayoutCandidates(files) {
+  const preferred = [
+    'src/app/layout.tsx',
+    'app/layout.tsx',
+    'src/pages/_app.tsx',
+    'pages/_app.tsx',
+    'src/main.tsx',
+    'src/App.tsx',
+    'index.html',
+  ];
+  const fileSet = new Set(files);
+  return preferred.filter(file => fileSet.has(file));
+}
+
+async function readInstructionFiles(cwd) {
+  const files = [];
+  for (const candidate of INSTRUCTION_FILE_CANDIDATES) {
+    const absolutePath = path.join(cwd, candidate.path);
+    const exists = await pathExists(absolutePath);
+    files.push({
+      ...candidate,
+      exists,
+      content: exists ? await fs.readFile(absolutePath, 'utf8').catch(() => '') : '',
+    });
+  }
+  return files.sort((a, b) => {
+    if (a.exists !== b.exists) return a.exists ? -1 : 1;
+    return a.priority - b.priority;
+  });
+}
+
+function detectContentFiles(files) {
+  return files.filter(file => (
+    /\.(md|mdx)$/.test(file) &&
+    /(^|\/)(blog|blogs|posts|articles|content|docs|guides|resources)(\/|$)/.test(file)
+  )).slice(0, 50);
+}
+
+function detectDeployHints(files, packageJson) {
+  const hints = [];
+  const fileSet = new Set(files);
+  if (fileSet.has('vercel.json')) hints.push('vercel.json');
+  if (fileSet.has('netlify.toml')) hints.push('netlify.toml');
+  if (fileSet.has('wrangler.toml')) hints.push('wrangler.toml');
+  if (fileSet.has('firebase.json')) hints.push('firebase.json');
+  if (packageJson?.scripts?.deploy) hints.push('package.json scripts.deploy');
+  return hints;
+}
+
+function routeSort(a, b) {
+  if (a === '/') return -1;
+  if (b === '/') return 1;
+  return a.localeCompare(b);
+}
+
+function toPosix(value) {
+  return value.split(path.sep).filter(Boolean).join('/');
+}

package/src/initialization.js

@@ -0,0 +1,148 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export async function buildInitializationPayload(plan, options = {}) {
+  const appName = titleFromPackageName(plan.repo.packageJson?.name ?? plan.appId);
+  const docs = await readProjectDocs(plan.cwd);
+  const publicBlogRoute = plan.repo.routes.find(route => route === '/blog' || route.startsWith('/blog/'));
+  const claims = [
+    {
+      category: 'repo',
+      claim: `The repo package name is ${plan.repo.packageJson?.name ?? appName}.`,
+      confidence: 'high',
+      sources: [{ type: 'file', reference: 'package.json' }],
+      needsReview: false,
+    },
+    {
+      category: 'stack',
+      claim: `The repo appears to use ${plan.repo.framework}.`,
+      confidence: plan.repo.framework === 'unknown' ? 'low' : 'high',
+      sources: [{ type: 'file', reference: 'package.json' }],
+      needsReview: plan.repo.framework === 'unknown',
+    },
+  ];
+
+  if (publicBlogRoute) {
+    claims.push({
+      category: 'distribution',
+      claim: `The app has a public blog route at ${publicBlogRoute}.`,
+      confidence: 'high',
+      sources: [{ type: 'file', reference: routeReference(publicBlogRoute, plan.repo.files) }],
+      needsReview: false,
+    });
+  }
+
+  if (docs.overview) {
+    claims.push({
+      category: 'positioning',
+      claim: docs.overview.claim,
+      confidence: 'medium',
+      sources: [{ type: 'file', reference: docs.overview.file, excerpt: docs.overview.excerpt }],
+      needsReview: true,
+    });
+  }
+
+  return {
+    appId: plan.appId,
+    client: 'distributionos-cli',
+    instructionPackVersion: plan.instructionPackVersion,
+    sourceSummary: 'DistributionOS CLI inspected package metadata, routes, content files, deploy hints, and agent instruction files. It did not read .env files or secrets.',
+    appIdentity: {
+      name: appName,
+      domain: options.domain,
+      description: docs.overview?.claim,
+    },
+    repo: {
+      root: path.basename(plan.cwd),
+      defaultBranch: plan.repo.git.branch ?? null,
+      frameworks: [plan.repo.framework].filter(value => value && value !== 'unknown'),
+      languages: ['TypeScript', 'JavaScript'],
+      packageManagers: [plan.repo.packageManager].filter(value => value && value !== 'unknown'),
+      notableFiles: [
+        'package.json',
+        ...plan.repo.layoutCandidates,
+        ...plan.repo.contentFiles.slice(0, 12),
+      ],
+    },
+    distribution: {
+      blogRoute: publicBlogRoute ?? undefined,
+      analytics: plan.analytics.status === 'enabled'
+        ? ['DistributionOS first-party analytics contract was available during setup.']
+        : [],
+    },
+    claims,
+    unknowns: [
+      'CLI setup did not verify live traffic, revenue, pricing, or customer claims.',
+      ...(plan.analytics.status === 'enabled' ? [] : ['Analytics tracker was not enabled or fetched during initialization.']),
+    ],
+    risks: [
+      'Review generated Brain Doc positioning before DistributionOS uses this context for public distribution work.',
+    ],
+    nextSteps: [
+      'Review the generated Brain Doc in DistributionOS.',
+      'Connect Search Console if it is not connected.',
+      'Verify analytics after deploying the tracker to a public URL.',
+    ],
+  };
+}
+
+export async function submitInitialization({ plan, token, apiBase, fetchImpl, domain }) {
+  const payload = await buildInitializationPayload(plan, { domain });
+  const response = await fetchImpl(`${apiBase.replace(/\/+$/, '')}/api/v1/apps/${encodeURIComponent(plan.appId)}/onboarding/initialize`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify(payload),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    throw new Error(body?.error || `Initialization submit failed with HTTP ${response.status}`);
+  }
+  return body?.data ?? body;
+}
+
+async function readProjectDocs(cwd) {
+  for (const file of ['README.md', 'CLAUDE.md', 'AGENTS.md']) {
+    const text = await fs.readFile(path.join(cwd, file), 'utf8').catch(() => '');
+    const excerpt = extractOverviewExcerpt(text);
+    if (excerpt) {
+      return {
+        overview: {
+          file,
+          excerpt,
+          claim: excerpt.replace(/\s+/g, ' ').slice(0, 500),
+        },
+      };
+    }
+  }
+  return {};
+}
+
+function extractOverviewExcerpt(text) {
+  const normalized = text.replace(/\r\n/g, '\n');
+  const overviewIndex = normalized.search(/(^|\n)#{1,3}\s+(Project Overview|Overview|Solution|What it does)\s*\n/i);
+  const source = overviewIndex >= 0 ? normalized.slice(overviewIndex) : normalized;
+  return source
+    .split(/\n{2,}/)
+    .map(block => block.replace(/^#{1,6}\s+[^\n]+\n?/, '').trim())
+    .find(block => block.length >= 80 && !/secret|api key|environment variables/i.test(block))
+    ?.slice(0, 700) ?? null;
+}
+
+function routeReference(route, files) {
+  if (route === '/blog' && files.includes('src/app/blog/page.tsx')) return 'src/app/blog/page.tsx';
+  if (route.startsWith('/blog/') && files.includes('src/app/blog/[slug]/page.tsx')) return 'src/app/blog/[slug]/page.tsx';
+  return route;
+}
+
+function titleFromPackageName(value) {
+  return String(value)
+    .replace(/^@[^/]+\//, '')
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ') || 'App';
+}

package/src/mutate.js

@@ -0,0 +1,193 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+const BOOTSTRAP_BLOCK_RE =
+  /<!--\s*DISTRIBUTIONOS:START[\s\S]*?DISTRIBUTIONOS:END\s*-->/i;
+const ANALYTICS_BLOCK_RE =
+  /\s*{\s*\/\*\s*DISTRIBUTIONOS:START analytics[\s\S]*?DISTRIBUTIONOS:END analytics\s*\*\/\s*}\s*/i;
+const HTML_ANALYTICS_BLOCK_RE =
+  /\s*<!--\s*DISTRIBUTIONOS:START analytics\s*-->[\s\S]*?<!--\s*DISTRIBUTIONOS:END analytics\s*-->\s*/i;
+
+export async function applySetupPlan(plan, options = {}) {
+  if (plan.repo.git.dirty && !options.allowDirty) {
+    throw new Error('Refusing to apply changes to a dirty worktree. Commit/stash changes or pass --allow-dirty.');
+  }
+
+  const changes = [];
+  const bootstrap = await applyBootstrap(plan.cwd, plan.bootstrap);
+  if (bootstrap.changed) changes.push(bootstrap);
+
+  if (!options.skipAnalytics) {
+    const analytics = await applyAnalytics(plan.cwd, plan.analytics);
+    if (analytics.changed || analytics.reason) changes.push(analytics);
+  }
+
+  return changes;
+}
+
+async function applyBootstrap(cwd, bootstrap) {
+  const targetPath = safeResolve(cwd, bootstrap.target);
+  const block = bootstrap.recommendedBlock.trim();
+
+  if (bootstrap.action === 'none') {
+    return { type: 'bootstrap', changed: false, file: bootstrap.target, reason: 'Already current.' };
+  }
+
+  if (bootstrap.action === 'create') {
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, `${block}\n`, 'utf8');
+    return { type: 'bootstrap', changed: true, file: bootstrap.target, action: 'created' };
+  }
+
+  const existing = await fs.readFile(targetPath, 'utf8').catch(() => '');
+  const next = bootstrap.action === 'update'
+    ? existing.replace(BOOTSTRAP_BLOCK_RE, block)
+    : `${existing.replace(/\s*$/, '\n\n')}${block}\n`;
+
+  if (next !== existing) {
+    await fs.writeFile(targetPath, next, 'utf8');
+    return { type: 'bootstrap', changed: true, file: bootstrap.target, action: bootstrap.action };
+  }
+  return { type: 'bootstrap', changed: false, file: bootstrap.target, reason: 'No text change needed.' };
+}
+
+async function applyAnalytics(cwd, analytics) {
+  if (analytics.status !== 'enabled') {
+    return { type: 'analytics', changed: false, file: null, reason: 'Analytics contract is not enabled.' };
+  }
+  if (!analytics.layoutTarget) {
+    return { type: 'analytics', changed: false, file: null, reason: 'No supported shared layout was detected.' };
+  }
+  const scriptSrc = analytics.scriptUrl ?? scriptSrcFromTag(analytics.scriptTag);
+  if (!scriptSrc) {
+    return { type: 'analytics', changed: false, file: analytics.layoutTarget, reason: 'Analytics contract did not include a script URL.' };
+  }
+
+  if (analytics.layoutTarget.endsWith('app/layout.tsx')) {
+    return applyNextAppRouterAnalytics(cwd, analytics, scriptSrc);
+  }
+
+  if (analytics.layoutTarget === 'index.html') {
+    return applyHtmlAnalytics(cwd, analytics, scriptSrc);
+  }
+
+  return {
+    type: 'analytics',
+    changed: false,
+    file: analytics.layoutTarget,
+    reason: 'Only Next App Router layout.tsx and index.html are auto-supported in this MVP.',
+  };
+}
+
+async function applyNextAppRouterAnalytics(cwd, analytics, scriptSrc) {
+  const targetPath = safeResolve(cwd, analytics.layoutTarget);
+  const existing = await fs.readFile(targetPath, 'utf8');
+  if (existing.includes(scriptSrc) && !ANALYTICS_BLOCK_RE.test(existing)) {
+    return { type: 'analytics', changed: false, file: analytics.layoutTarget, reason: 'Analytics script URL already exists outside the managed block.' };
+  }
+
+  const block = buildNextAnalyticsBlock({
+    scriptSrc,
+    contractVersion: analytics.contractVersion,
+    configScript: analytics.configScript,
+  });
+  const next = ANALYTICS_BLOCK_RE.test(existing)
+    ? existing.replace(ANALYTICS_BLOCK_RE, `\n${block}\n`)
+    : insertBeforeHeadClose(existing, block);
+
+  if (next === existing) {
+    return { type: 'analytics', changed: false, file: analytics.layoutTarget, reason: 'No analytics change needed.' };
+  }
+
+  await fs.writeFile(targetPath, next, 'utf8');
+  return { type: 'analytics', changed: true, file: analytics.layoutTarget, action: 'installed' };
+}
+
+async function applyHtmlAnalytics(cwd, analytics, scriptSrc) {
+  const targetPath = safeResolve(cwd, analytics.layoutTarget);
+  const existing = await fs.readFile(targetPath, 'utf8');
+  if (existing.includes(scriptSrc) && !HTML_ANALYTICS_BLOCK_RE.test(existing)) {
+    return { type: 'analytics', changed: false, file: analytics.layoutTarget, reason: 'Analytics script URL already exists outside the managed block.' };
+  }
+
+  const block = buildHtmlAnalyticsBlock({
+    scriptSrc,
+    contractVersion: analytics.contractVersion,
+    configScript: analytics.configScript,
+  });
+  const next = HTML_ANALYTICS_BLOCK_RE.test(existing)
+    ? existing.replace(HTML_ANALYTICS_BLOCK_RE, `\n${block}\n`)
+    : insertBeforeHeadClose(existing, block);
+
+  if (next === existing) {
+    return { type: 'analytics', changed: false, file: analytics.layoutTarget, reason: 'No analytics change needed.' };
+  }
+
+  await fs.writeFile(targetPath, next, 'utf8');
+  return { type: 'analytics', changed: true, file: analytics.layoutTarget, action: 'installed' };
+}
+
+function buildNextAnalyticsBlock({ scriptSrc, contractVersion, configScript }) {
+  const config = configScript || `window.distributionOSAnalyticsConfig = { contractVersion: ${JSON.stringify(contractVersion)} };`;
+  return [
+    '        {/* DISTRIBUTIONOS:START analytics */}',
+    '        <script',
+    '          dangerouslySetInnerHTML={{',
+    `            __html: ${JSON.stringify(config)},`,
+    '          }}',
+    '        />',
+    '        <script',
+    '          async',
+    `          src=${JSON.stringify(scriptSrc)}`,
+    '        />',
+    '        {/* DISTRIBUTIONOS:END analytics */}',
+  ].join('\n');
+}
+
+function buildHtmlAnalyticsBlock({ scriptSrc, contractVersion, configScript }) {
+  const config = configScript || `window.distributionOSAnalyticsConfig = { contractVersion: ${JSON.stringify(contractVersion)} };`;
+  return [
+    '    <!-- DISTRIBUTIONOS:START analytics -->',
+    '    <script>',
+    indentLines(config, '      '),
+    '    </script>',
+    `    <script async src="${escapeHtmlAttribute(scriptSrc)}"></script>`,
+    '    <!-- DISTRIBUTIONOS:END analytics -->',
+  ].join('\n');
+}
+
+function insertBeforeHeadClose(content, block) {
+  const headClose = content.match(/^(\s*)<\/head>/im);
+  if (headClose?.index === undefined) {
+    throw new Error('Could not find </head> in shared layout.');
+  }
+  return `${content.slice(0, headClose.index)}${block}\n${content.slice(headClose.index)}`;
+}
+
+function indentLines(value, prefix) {
+  return String(value).split(/\r?\n/).map(line => `${prefix}${line}`).join('\n');
+}
+
+function escapeHtmlAttribute(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function scriptSrcFromTag(scriptTag) {
+  if (!scriptTag) return null;
+  const match = String(scriptTag).match(/\ssrc=["']([^"']+)["']/i);
+  return match?.[1] ?? null;
+}
+
+function safeResolve(cwd, relativePath) {
+  const root = path.resolve(cwd);
+  const target = path.resolve(root, relativePath);
+  const relative = path.relative(root, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Refusing to write outside repo root: ${relativePath}`);
+  }
+  return target;
+}