@distributionos/cli 0.1.0

package/src/oauth.js

@@ -0,0 +1,238 @@
+import { createHash, randomBytes } from 'node:crypto';
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { storeCredential } from './auth-store.js';
+import { DEFAULT_API_BASE } from './constants.js';
+
+export async function loginWithOAuth(options) {
+  const apiBase = normalizeApiBase(options.apiBase ?? DEFAULT_API_BASE);
+  const callback = await createCallbackServer();
+  const redirectUri = `http://127.0.0.1:${callback.port}/callback`;
+  const verifier = randomSecret(48);
+  const challenge = pkceChallenge(verifier);
+  const state = randomSecret(24);
+
+  try {
+    const client = await registerClient({
+      fetchImpl: options.fetch,
+      apiBase,
+      redirectUri,
+    });
+    const authorizeUrl = buildAuthorizeUrl({
+      apiBase,
+      appId: options.appId,
+      clientId: client.client_id,
+      redirectUri,
+      challenge,
+      state,
+    });
+
+    options.stdout?.write([
+      'Open this DistributionOS authorization URL:',
+      authorizeUrl,
+      '',
+    ].join('\n'));
+    if (options.openBrowser !== false) openUrl(authorizeUrl);
+
+    const authResult = await callback.waitForCallback();
+    if (authResult.state !== state) throw new Error('OAuth callback state did not match.');
+    if (authResult.error) throw new Error(`OAuth failed: ${authResult.error}`);
+    if (!authResult.code) throw new Error('OAuth callback did not include an authorization code.');
+
+    const tokens = await exchangeCode({
+      fetchImpl: options.fetch,
+      apiBase,
+      clientId: client.client_id,
+      redirectUri,
+      verifier,
+      code: authResult.code,
+    });
+    const credential = credentialFromTokenResponse(tokens);
+    await storeCredential({
+      apiBase,
+      appId: options.appId,
+      credential: {
+        type: 'oauth',
+        clientId: client.client_id,
+        ...credential,
+      },
+      env: options.env,
+    });
+    return credential;
+  } finally {
+    await callback.close();
+  }
+}
+
+export async function refreshOAuthCredential({ credential, apiBase, appId, fetchImpl, env }) {
+  if (!credential?.refreshToken) return null;
+  const response = await postForm(fetchImpl, `${normalizeApiBase(apiBase)}/oauth/token`, {
+    grant_type: 'refresh_token',
+    refresh_token: credential.refreshToken,
+    scope: 'read write',
+  });
+  const next = {
+    ...credential,
+    ...credentialFromTokenResponse(response),
+    clientId: credential.clientId,
+    type: 'oauth',
+  };
+  await storeCredential({ apiBase, appId, credential: next, env });
+  return next;
+}
+
+export function isCredentialFresh(credential, skewMs = 5 * 60 * 1000) {
+  if (!credential?.accessToken || !credential.expiresAt) return false;
+  return new Date(credential.expiresAt).getTime() - skewMs > Date.now();
+}
+
+function credentialFromTokenResponse(tokens) {
+  const expiresAt = new Date(Date.now() + Number(tokens.expires_in ?? 0) * 1000).toISOString();
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    tokenType: tokens.token_type ?? 'Bearer',
+    scope: tokens.scope ?? 'read write',
+    expiresAt,
+  };
+}
+
+async function registerClient({ fetchImpl, apiBase, redirectUri }) {
+  const response = await fetchImpl(`${apiBase}/oauth/register`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({
+      client_name: 'DistributionOS CLI',
+      redirect_uris: [redirectUri],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'none',
+    }),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new Error(body?.error_description || body?.error || `Client registration failed with HTTP ${response.status}`);
+  }
+  return body;
+}
+
+function buildAuthorizeUrl({ apiBase, appId, clientId, redirectUri, challenge, state }) {
+  const url = new URL(`${apiBase}/oauth/authorize`);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('code_challenge', challenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  url.searchParams.set('scope', 'read write');
+  url.searchParams.set('resource', `${apiBase}/api/mcp`);
+  url.searchParams.set('state', state);
+  url.searchParams.set('appId', appId);
+  return url.toString();
+}
+
+async function exchangeCode({ fetchImpl, apiBase, clientId, redirectUri, verifier, code }) {
+  return postForm(fetchImpl, `${apiBase}/oauth/token`, {
+    grant_type: 'authorization_code',
+    code,
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    code_verifier: verifier,
+    resource: `${apiBase}/api/mcp`,
+  });
+}
+
+async function postForm(fetchImpl, url, fields) {
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams(fields),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new Error(body?.error_description || body?.error || `OAuth token request failed with HTTP ${response.status}`);
+  }
+  return body;
+}
+
+async function createCallbackServer() {
+  let resolveCallback;
+  let rejectCallback;
+  const callbackPromise = new Promise((resolve, reject) => {
+    resolveCallback = resolve;
+    rejectCallback = reject;
+  });
+
+  const server = http.createServer((request, response) => {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    if (url.pathname !== '/callback') {
+      response.writeHead(404).end('Not found');
+      return;
+    }
+    const payload = {
+      code: url.searchParams.get('code'),
+      state: url.searchParams.get('state'),
+      error: url.searchParams.get('error'),
+    };
+    response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    response.end('<h1>DistributionOS CLI connected</h1><p>You can return to your terminal.</p>');
+    resolveCallback(payload);
+  });
+
+  server.on('error', rejectCallback);
+  await new Promise((resolve, reject) => {
+    server.listen(0, '127.0.0.1', error => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+
+  const address = server.address();
+  const timeout = setTimeout(() => {
+    rejectCallback(new Error('OAuth login timed out.'));
+  }, 5 * 60 * 1000);
+
+  return {
+    port: address.port,
+    waitForCallback: async () => {
+      try {
+        return await callbackPromise;
+      } finally {
+        clearTimeout(timeout);
+      }
+    },
+    close: () => new Promise(resolve => server.close(resolve)),
+  };
+}
+
+function openUrl(url) {
+  const command = process.platform === 'win32'
+    ? 'cmd'
+    : process.platform === 'darwin'
+      ? 'open'
+      : 'xdg-open';
+  const args = process.platform === 'win32'
+    ? ['/c', 'start', '""', url]
+    : [url];
+  try {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref();
+  } catch {
+    // The printed URL is the reliable fallback.
+  }
+}
+
+function pkceChallenge(verifier) {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+function randomSecret(bytes) {
+  return randomBytes(bytes).toString('base64url');
+}
+
+function normalizeApiBase(value) {
+  return String(value || DEFAULT_API_BASE).replace(/\/+$/, '');
+}

package/src/plan.js

@@ -0,0 +1,265 @@
+import { fetchDistributionOsSetupContext } from './api.js';
+import {
+  CLI_PACKAGE_NAME,
+  CURRENT_BOOTSTRAP_VERSION,
+  DEFAULT_API_BASE,
+} from './constants.js';
+import {
+  buildFallbackMcpInstructions,
+  buildLocalBootstrapBlock,
+  buildSetupCommand,
+  getBootstrapAction,
+} from './bootstrap.js';
+import { scanRepo } from './detect.js';
+import {
+  buildAnalyticsRouteConfigScript,
+  buildAnalyticsRouteConfigSnippet,
+} from './privacy.js';
+
+export async function createSetupPlan(options) {
+  const cwd = options.cwd;
+  const appId = options.appId;
+  const repo = await scanRepo(cwd);
+  const remote = await fetchDistributionOsSetupContext({
+    appId,
+    apiBase: options.apiBase ?? DEFAULT_API_BASE,
+    env: options.env,
+    fetch: options.fetch,
+    noFetch: options.noFetch,
+  });
+  const instructionPackVersion =
+    remote.instructions?.instructionPackVersion ?? CURRENT_BOOTSTRAP_VERSION;
+  const recommendedBootstrapBlock =
+    remote.instructions?.recommendedBootstrapBlock ??
+    buildLocalBootstrapBlock(instructionPackVersion, appId);
+  const bootstrap = getBootstrapAction(repo.instructionFiles, recommendedBootstrapBlock);
+  const analyticsContract = remote.analyticsContract;
+  const planRepo = sanitizeRepoForPlan(repo);
+
+  return {
+    appId,
+    cwd,
+    mode: options.apply ? 'apply' : 'dry-run',
+    packageName: CLI_PACKAGE_NAME,
+    futureCommand: buildSetupCommand(appId),
+    localCommand: `npm run cli:setup -- --app ${appId}`,
+    apiBase: options.apiBase ?? DEFAULT_API_BASE,
+    repo: planRepo,
+    remote,
+    instructionPackVersion,
+    bootstrap,
+    analytics: buildAnalyticsPlan({ analyticsContract, repo: planRepo, instructionPackVersion }),
+    fallbackInstructions: buildFallbackMcpInstructions(appId),
+    warnings: buildWarnings({ repo: planRepo, remote }),
+    validation: buildValidationPlan(planRepo),
+    deploymentChecklist: [
+      'Review this plan and any proposed file edits.',
+      'Apply reviewed bootstrap and analytics changes only.',
+      'Run baseline tests before mutation when the worktree is messy.',
+      'Run build and test commands after mutation.',
+      'Do not deploy until a human reviews the diff.',
+      'After deployment, call verify_analytics_install on representative public URLs.',
+      'Call report_implementation for shipped artifacts or analytics opt-outs.',
+    ],
+  };
+}
+
+function sanitizeRepoForPlan(repo) {
+  return {
+    ...repo,
+    packageJson: sanitizePackageJson(repo.packageJson),
+    instructionFiles: (repo.instructionFiles ?? []).map(file => ({
+      path: file.path,
+      priority: file.priority,
+      exists: file.exists,
+      hasManagedDistributionOsBlock: /<!--\s*DISTRIBUTIONOS:START[\s\S]*?DISTRIBUTIONOS:END\s*-->/i.test(file.content ?? ''),
+      contentOmitted: true,
+    })),
+  };
+}
+
+function sanitizePackageJson(packageJson) {
+  if (!packageJson) return null;
+  return {
+    name: typeof packageJson.name === 'string' ? packageJson.name : undefined,
+    version: typeof packageJson.version === 'string' ? packageJson.version : undefined,
+    private: typeof packageJson.private === 'boolean' ? packageJson.private : undefined,
+  };
+}
+
+export function formatPlanText(plan) {
+  const lines = [
+    'DistributionOS CLI setup plan',
+    `App: ${plan.appId}`,
+    plan.mode === 'apply'
+      ? 'Mode: apply'
+      : 'Mode: dry-run (no files changed)',
+    `Package: ${plan.packageName}`,
+    `Future command: ${plan.futureCommand}`,
+    `Local command: ${plan.localCommand}`,
+    '',
+    'Repository',
+    `- Root: ${plan.cwd}`,
+    `- Git: ${plan.repo.git.isGitRepo ? (plan.repo.git.dirty ? 'dirty worktree' : 'clean worktree') : 'not detected'}`,
+    `- Framework: ${plan.repo.framework}`,
+    `- Package manager: ${plan.repo.packageManager}`,
+    `- Layout candidates: ${formatList(plan.repo.layoutCandidates)}`,
+    `- Content files found: ${plan.repo.contentFiles.length}`,
+    `- Deploy hints: ${formatList(plan.repo.deployHints)}`,
+    '',
+    'DistributionOS access',
+    remoteSummary(plan),
+    ...plan.remote.errors.map(error => `- ${error}`),
+    '',
+    'Planned changes',
+    `1. Agent bootstrap: ${plan.bootstrap.action} ${plan.bootstrap.target}`,
+    `   ${plan.bootstrap.reason}`,
+    `2. Agent instructions: ${plan.remote.instructions ? 'use fetched current instruction pack' : 'use fallback MCP/OAuth instructions until authenticated'}`,
+    `3. Analytics: ${analyticsSummary(plan.analytics)}`,
+    '',
+    'Route privacy review',
+    `- Allowed public candidates: ${formatList(plan.repo.routePrivacy.allowed, 8)}`,
+    `- Blocked private candidates: ${formatList(plan.repo.routePrivacy.blocked, 8)}`,
+    `- Needs review: ${formatList(plan.repo.routePrivacy.review, 8)}`,
+    '',
+    'Validation',
+    `- Build: ${plan.validation.build ?? 'not detected'}`,
+    `- Test: ${plan.validation.test ?? 'not detected'}`,
+    `- Lint: ${plan.validation.lint ?? 'not detected'}`,
+    '',
+    'Fallback MCP/OAuth instructions',
+    ...plan.fallbackInstructions.map(item => `- ${item}`),
+    '',
+    'Deployment checklist',
+    ...plan.deploymentChecklist.map(item => `- ${item}`),
+  ];
+
+  if (plan.analytics.configSnippet) {
+    lines.push('', 'Future-compatible route gate config', plan.analytics.configSnippet);
+  }
+
+  if (plan.warnings.length > 0) {
+    lines.push('', 'Warnings', ...plan.warnings.map(item => `- ${item}`));
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function buildAnalyticsPlan({ analyticsContract, repo, instructionPackVersion }) {
+  const layoutTarget = selectAnalyticsLayoutTarget(repo);
+  if (!analyticsContract) {
+    return {
+      status: 'not_fetched',
+      scriptTag: null,
+      scriptUrl: null,
+      layoutTarget,
+      contractVersion: null,
+      configSnippet: buildAnalyticsRouteConfigSnippet(instructionPackVersion),
+      configScript: buildAnalyticsRouteConfigScript(instructionPackVersion),
+      notes: [
+        'No authenticated analytics contract was fetched.',
+        'Create or fetch the tracker in DistributionOS before applying analytics changes.',
+      ],
+    };
+  }
+
+  if (analyticsContract.status !== 'enabled') {
+    return {
+      status: analyticsContract.status,
+      scriptTag: null,
+      scriptUrl: null,
+      layoutTarget,
+      contractVersion: analyticsContract.version ?? null,
+      configSnippet: buildAnalyticsRouteConfigSnippet(analyticsContract.version),
+      configScript: buildAnalyticsRouteConfigScript(analyticsContract.version),
+      notes: analyticsContract.installInstructions ?? [],
+    };
+  }
+
+  return {
+    status: 'enabled',
+    scriptTag: analyticsContract.scriptTag ?? null,
+    scriptUrl: analyticsContract.scriptUrl ?? null,
+    layoutTarget,
+    contractVersion: analyticsContract.version ?? null,
+    configSnippet: buildAnalyticsRouteConfigSnippet(analyticsContract.version),
+    configScript: buildAnalyticsRouteConfigScript(analyticsContract.version),
+    notes: [
+      'Install the fetched script exactly once in the shared public layout.',
+      'Preserve clean canonical URLs.',
+      'Backfill public blog and landing pages with stable dosContentId markers.',
+      'Add data-dos-event and data-dos-link-id only to primary CTAs or campaign links.',
+    ],
+  };
+}
+
+function selectAnalyticsLayoutTarget(repo) {
+  const candidates = repo.layoutCandidates ?? [];
+  if (repo.framework === 'next') {
+    return candidates.find(file => file.endsWith('app/layout.tsx')) ??
+      candidates.find(file => file.endsWith('pages/_app.tsx')) ??
+      candidates[0] ??
+      null;
+  }
+
+  if (['vite', 'vite-react', 'create-react-app', 'react'].includes(repo.framework)) {
+    return candidates.find(file => file === 'index.html') ?? candidates[0] ?? null;
+  }
+
+  return candidates[0] ?? null;
+}
+
+function buildWarnings({ repo, remote }) {
+  const warnings = [];
+  if (repo.git.dirty) {
+    warnings.push('Worktree has existing changes. Keep baseline failures separate before applying edits.');
+  }
+  if (!remote.instructions) {
+    warnings.push('Live DistributionOS instructions were not fetched. Connect MCP OAuth or provide a safe env token before applying app-specific setup.');
+  }
+  if (!remote.analyticsContract) {
+    warnings.push('Analytics contract was not fetched. Do not install tracker code from stale/manual instructions.');
+  }
+  if (repo.routePrivacy.review.length > 0) {
+    warnings.push('Some routes need human review before analytics markers are applied.');
+  }
+  if (repo.framework === 'unknown') {
+    warnings.push('Framework was not recognized. Use printed manual steps instead of automatic mutation.');
+  }
+  return warnings;
+}
+
+function buildValidationPlan(repo) {
+  return {
+    build: repo.commands.build,
+    test: repo.commands.test,
+    lint: repo.commands.lint,
+  };
+}
+
+function remoteSummary(plan) {
+  if (plan.remote.status === 'fetched') {
+    return `- Fetched live instructions and analytics contract using ${plan.remote.tokenName}.`;
+  }
+  if (plan.remote.status === 'partial') {
+    return `- Used ${plan.remote.tokenName}, but one or more DistributionOS requests failed.`;
+  }
+  return '- No env token found. Dry-run used local fallback instructions and did not call DistributionOS APIs.';
+}
+
+function analyticsSummary(analytics) {
+  if (analytics.status === 'enabled') {
+    return `contract ${analytics.contractVersion}; install script in ${analytics.layoutTarget ?? 'reviewed shared layout'}`;
+  }
+  if (analytics.status === 'disabled') {
+    return 'tracker is not enabled yet; create tracker in DistributionOS first';
+  }
+  return 'contract not fetched; print manual guidance only';
+}
+
+function formatList(values, limit = 5) {
+  if (!values || values.length === 0) return 'none';
+  const shown = values.slice(0, limit).join(', ');
+  const remaining = values.length - limit;
+  return remaining > 0 ? `${shown}, +${remaining} more` : shown;
+}

package/src/privacy.js

@@ -0,0 +1,62 @@
+import {
+  CURRENT_ANALYTICS_CONTRACT_VERSION,
+  PRIVATE_ROUTE_PATTERNS,
+  PUBLIC_ROUTE_PATTERNS,
+} from './constants.js';
+
+const privateRegexes = PRIVATE_ROUTE_PATTERNS.map(patternToRegex);
+const publicRegexes = PUBLIC_ROUTE_PATTERNS.map(patternToRegex);
+
+export function classifyRoute(route) {
+  const normalized = normalizeRoute(route);
+  if (privateRegexes.some((regex) => regex.test(normalized))) return 'blocked';
+  if (publicRegexes.some((regex) => regex.test(normalized))) return 'allowed';
+  return 'review';
+}
+
+export function groupRoutesByPrivacy(routes) {
+  const grouped = {
+    allowed: [],
+    blocked: [],
+    review: [],
+  };
+
+  for (const route of routes) {
+    grouped[classifyRoute(route)].push(route);
+  }
+
+  return grouped;
+}
+
+export function buildAnalyticsRouteConfigSnippet(version = CURRENT_ANALYTICS_CONTRACT_VERSION) {
+  return [
+    '<script>',
+    buildAnalyticsRouteConfigScript(version),
+    '</script>',
+  ].join('\n');
+}
+
+export function buildAnalyticsRouteConfigScript(version = CURRENT_ANALYTICS_CONTRACT_VERSION) {
+  return [
+    'window.distributionOSAnalyticsConfig = window.distributionOSAnalyticsConfig || {};',
+    'window.distributionOSAnalyticsConfig.contractVersion = ' + JSON.stringify(version) + ';',
+    'window.distributionOSAnalyticsConfig.routePrivacy = {',
+    `  allow: ${JSON.stringify(PUBLIC_ROUTE_PATTERNS)},`,
+    `  block: ${JSON.stringify(PRIVATE_ROUTE_PATTERNS)}`,
+    '};',
+  ].join('\n');
+}
+
+export function normalizeRoute(route) {
+  const trimmed = String(route || '').trim();
+  if (!trimmed || trimmed === '/') return '/';
+  return `/${trimmed.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+}
+
+function patternToRegex(pattern) {
+  if (pattern === '/') return /^\/$/;
+  const escaped = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\/\*\*$/g, '(?:/.*)?');
+  return new RegExp(`^${escaped}$`);
+}