@distributionos/cli 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# DistributionOS CLI
+
+Local installer for connecting an app repo to DistributionOS.
+
+```bash
+npx @distributionos/cli setup --app <appId>
+```
+
+Default setup opens the DistributionOS MCP OAuth approval flow when needed, then prints a plan first. In an interactive terminal, approve the plan to apply the managed setup changes. In non-interactive agent runs, use `--apply` only after reviewing the dry-run output.
+
+Before the package is published, test the local package from another repo with:
+
+```bash
+npm exec --yes --package "C:\Users\lawre\DistributionOS\packages\cli" -- distributionos setup --app <appId> --api-base http://localhost:3005
+```
+
+## Commands
+
+```bash
+distributionos setup --app <appId>
+distributionos setup --app <appId> --apply
+distributionos login --app <appId>
+distributionos verify --app <appId> --url <liveUrl> [--content-id <id>]
+distributionos report-implementation --app <appId> --artifact <artifactId> [--url <liveUrl>]
+```
+
+## Safety
+
+- Uses DistributionOS MCP OAuth as the happy path.
+- Stores OAuth credentials outside the app repo.
+- Accepts API-key environment variables only as an advanced fallback.
+- Does not write secrets into committed files.
+- Scans repo structure without reading `.env` or credential-looking files.
+- Redacts secret-looking validation output before printing or serializing results.
+- Mutates only the managed DistributionOS bootstrap block and supported analytics install.
+- Auto-installs analytics for Next App Router layouts and Vite/CRA-style `index.html` entrypoints.
+- Refuses dirty worktrees unless `--allow-dirty` is explicit.
+- Does not commit, push, or deploy.

package/bin/distributionos.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+const code = await runCli(process.argv, {
+  cwd: process.cwd(),
+  env: process.env,
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  fetch: globalThis.fetch,
+});
+
+process.exitCode = code;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@distributionos/cli",
+  "version": "0.1.0",
+  "description": "DistributionOS repo setup CLI for agent onboarding and first-party analytics.",
+  "homepage": "https://distributionos.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lawfan1026/DistributionOS.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.js"
+  ],
+  "bin": {
+    "distributionos": "bin/distributionos.js",
+    "dos": "bin/distributionos.js"
+  },
+  "engines": {
+    "node": ">=18.18"
+  }
+}

package/src/api.js

@@ -0,0 +1,209 @@
+import { DEFAULT_API_BASE, TOKEN_ENV_NAMES } from './constants.js';
+import { getStoredCredential } from './auth-store.js';
+import { isCredentialFresh, refreshOAuthCredential } from './oauth.js';
+
+export function resolveEnvToken(env) {
+  for (const name of TOKEN_ENV_NAMES) {
+    const value = env?.[name]?.trim();
+    if (value) return { source: 'env', name, value };
+  }
+  return null;
+}
+
+export async function resolveAuthToken({ env, apiBase, appId, fetchImpl }) {
+  const envToken = resolveEnvToken(env);
+  if (envToken) return envToken;
+
+  const credential = await getStoredCredential({ apiBase, appId, env });
+  if (!credential) return null;
+  if (isCredentialFresh(credential)) {
+    return { source: 'oauth', name: 'stored OAuth token', value: credential.accessToken };
+  }
+
+  const refreshed = await refreshOAuthCredential({
+    credential,
+    apiBase,
+    appId,
+    fetchImpl,
+    env,
+  }).catch(() => null);
+
+  return refreshed?.accessToken
+    ? { source: 'oauth', name: 'refreshed OAuth token', value: refreshed.accessToken }
+    : null;
+}
+
+export async function fetchDistributionOsSetupContext(input) {
+  const token = await resolveAuthToken({
+    env: input.env,
+    apiBase: input.apiBase ?? DEFAULT_API_BASE,
+    appId: input.appId,
+    fetchImpl: input.fetch,
+  });
+  if (!token || input.noFetch) {
+    return {
+      status: 'not_authenticated',
+      tokenName: token?.name ?? null,
+      instructions: null,
+      analyticsContract: null,
+      errors: [],
+    };
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const errors = [];
+  const [instructions, analyticsContract] = await Promise.all([
+    fetchJson({
+      fetchImpl: input.fetch,
+      apiBase,
+      token: token.value,
+      path: `/api/v1/apps/${encodeURIComponent(input.appId)}/agent/instructions`,
+    }).catch(error => {
+      errors.push(`Agent instructions fetch failed: ${error.message}`);
+      return null;
+    }),
+    fetchJson({
+      fetchImpl: input.fetch,
+      apiBase,
+      token: token.value,
+      path: `/api/v1/apps/${encodeURIComponent(input.appId)}/analytics/contract`,
+    }).catch(error => {
+      errors.push(`Analytics contract fetch failed: ${error.message}`);
+      return null;
+    }),
+  ]);
+
+  return {
+    status: errors.length === 0 ? 'fetched' : 'partial',
+    tokenName: token.name,
+    instructions,
+    analyticsContract,
+    errors,
+  };
+}
+
+export async function ensureAnalyticsSite(input) {
+  const token = await resolveAuthToken({
+    env: input.env,
+    apiBase: input.apiBase ?? DEFAULT_API_BASE,
+    appId: input.appId,
+    fetchImpl: input.fetch,
+  });
+  if (!token) {
+    return {
+      status: 'not_authenticated',
+      setup: null,
+      error: 'No stored OAuth token or env token was available.',
+    };
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const response = await input.fetch(`${apiBase}/api/v1/apps/${encodeURIComponent(input.appId)}/analytics/sites`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token.value}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify({
+      ...(input.domain ? { domain: input.domain } : {}),
+      ownerVisitExclusionEnabled: input.ownerVisitExclusionEnabled,
+    }),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    return {
+      status: 'failed',
+      setup: null,
+      error: body?.error || `HTTP ${response.status}`,
+    };
+  }
+
+  return {
+    status: 'ready',
+    setup: body?.data ?? body,
+    error: null,
+  };
+}
+
+export async function verifyAnalyticsInstall(input) {
+  const token = await resolveAuthToken({
+    env: input.env,
+    apiBase: input.apiBase ?? DEFAULT_API_BASE,
+    appId: input.appId,
+    fetchImpl: input.fetch,
+  });
+  if (!token) {
+    throw new Error('No stored OAuth token or env token was available.');
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const response = await input.fetch(`${apiBase}/api/v1/apps/${encodeURIComponent(input.appId)}/analytics/verify`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token.value}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify({
+      url: input.url,
+      ...(input.expectedContentId ? { expectedContentId: input.expectedContentId } : {}),
+      ...(input.contractVersion ? { contractVersion: input.contractVersion } : {}),
+    }),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    throw new Error(body?.error || `Analytics verification failed with HTTP ${response.status}`);
+  }
+  return body?.data ?? body;
+}
+
+export async function reportImplementation(input) {
+  const token = await resolveAuthToken({
+    env: input.env,
+    apiBase: input.apiBase ?? DEFAULT_API_BASE,
+    appId: input.appId,
+    fetchImpl: input.fetch,
+  });
+  if (!token) {
+    throw new Error('No stored OAuth token or env token was available.');
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const response = await input.fetch(`${apiBase}/api/v1/apps/${encodeURIComponent(input.appId)}/artifacts/${encodeURIComponent(input.artifactId)}/report-implementation`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token.value}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify(input.payload),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    throw new Error(body?.error || `Implementation report failed with HTTP ${response.status}`);
+  }
+  return body?.data ?? body;
+}
+
+async function fetchJson({ fetchImpl, apiBase, token, path }) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable in this Node runtime');
+  }
+
+  const response = await fetchImpl(`${apiBase}${path}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+    },
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    throw new Error(body?.error || `HTTP ${response.status}`);
+  }
+  return body?.data ?? body;
+}
+
+function normalizeApiBase(value) {
+  return String(value || DEFAULT_API_BASE).replace(/\/+$/, '');
+}

package/src/auth-store.js

@@ -0,0 +1,52 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CONFIG_DIR = '.distributionos';
+const CONFIG_FILE = 'config.json';
+
+export function getConfigPath(env = process.env) {
+  if (env.DISTRIBUTIONOS_CONFIG) return env.DISTRIBUTIONOS_CONFIG;
+  return path.join(os.homedir(), CONFIG_DIR, CONFIG_FILE);
+}
+
+export async function loadConfig(env = process.env) {
+  try {
+    return JSON.parse(await fs.readFile(getConfigPath(env), 'utf8'));
+  } catch {
+    return { credentials: {} };
+  }
+}
+
+export async function saveConfig(config, env = process.env) {
+  const configPath = getConfigPath(env);
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function getStoredCredential({ apiBase, appId, env }) {
+  const config = await loadConfig(env);
+  return config.credentials?.[credentialKey(apiBase, appId)] ?? null;
+}
+
+export async function storeCredential({ apiBase, appId, credential, env }) {
+  const config = await loadConfig(env);
+  config.credentials = config.credentials ?? {};
+  config.credentials[credentialKey(apiBase, appId)] = {
+    ...credential,
+    apiBase,
+    appId,
+    updatedAt: new Date().toISOString(),
+  };
+  await saveConfig(config, env);
+}
+
+export async function removeCredential({ apiBase, appId, env }) {
+  const config = await loadConfig(env);
+  if (config.credentials) delete config.credentials[credentialKey(apiBase, appId)];
+  await saveConfig(config, env);
+}
+
+function credentialKey(apiBase, appId) {
+  return `${String(apiBase).replace(/\/+$/, '')}|${appId}`;
+}

package/src/bootstrap.js

@@ -0,0 +1,107 @@
+import {
+  CLI_PACKAGE_NAME,
+  CURRENT_BOOTSTRAP_VERSION,
+  MCP_SERVER_URL,
+} from './constants.js';
+
+const BOOTSTRAP_BLOCK_RE =
+  /<!--\s*DISTRIBUTIONOS:START[\s\S]*?DISTRIBUTIONOS:END\s*-->/i;
+
+export function buildSetupCommand(appId, packageName = CLI_PACKAGE_NAME) {
+  return `npx ${packageName} setup --app ${shellToken(appId)}`;
+}
+
+export function buildLocalBootstrapBlock(version = CURRENT_BOOTSTRAP_VERSION, appId) {
+  const appIdAttribute = appId ? ` appId=${appId}` : '';
+  const instructionCall = appId
+    ? `distributionos.get_agent_instructions({ appId: '${appId}', bootstrapVersion: '${version}' })`
+    : `distributionos.get_agent_instructions({ bootstrapVersion: '${version}' })`;
+
+  return [
+    `<!-- DISTRIBUTIONOS:START version=${version}${appIdAttribute} -->`,
+    '## DistributionOS Agent Sync',
+    '',
+    'This repo is linked to DistributionOS.',
+    '',
+    'Hard preflight: before editing files, creating assets, generating images, or changing copy for SEO, blog, launch, content, visual asset, competitor, social, email, or growth work, fetch the current instructions from DistributionOS:',
+    '',
+    instructionCall,
+    '',
+    'This preflight applies even when the user does not mention DistributionOS by name. Do not start from local repo files alone for those tasks.',
+    '',
+    'For existing blog posts or DistributionOS artifacts, fetch the artifact/context first. Use DistributionOS image/media workflows before local image tools.',
+    '',
+    'When you create a plan, strategy, roadmap, campaign, content ideas, keyword priorities, or next-step recommendations, save it to DistributionOS as proposed work for review before executing.',
+    '',
+    'When you publish, ship, schedule, or implement a DistributionOS artifact, report the implementation back to DistributionOS before your final response.',
+    '',
+    'If analytics is enabled, public blog posts, landing pages, CTAs, email links, social links, launch links, paid links, and campaigns must use the DistributionOS analytics contract by default: call get_analytics_install_instructions, add page/link markers, use create_tracked_link for campaign links, verify_analytics_install after deploy, or report a specific analyticsOptOutReason.',
+    '',
+    'For SEO blog/page publishes, verify 200, canonical, sitemap inclusion, robots/indexability, one H1, meta description, and schema before reporting.',
+    '',
+    'Never send secrets, env vars, API keys, private customer data, raw logs, or internal-only implementation details.',
+    '<!-- DISTRIBUTIONOS:END -->',
+  ].join('\n');
+}
+
+export function getBootstrapAction(instructionFiles, recommendedBlock) {
+  const existingWithBlock = instructionFiles.find((file) =>
+    BOOTSTRAP_BLOCK_RE.test(file.content ?? ''),
+  );
+  const preferred = existingWithBlock ?? instructionFiles[0] ?? {
+    path: 'AGENTS.md',
+    exists: false,
+    content: '',
+    priority: 100,
+  };
+
+  if (!preferred.exists) {
+    return {
+      action: 'create',
+      target: preferred.path,
+      reason: 'No agent instruction file was found. AGENTS.md is the safest cross-agent default.',
+      recommendedBlock,
+    };
+  }
+
+  const currentBlock = preferred.content.match(BOOTSTRAP_BLOCK_RE)?.[0] ?? null;
+  if (!currentBlock) {
+    return {
+      action: 'append',
+      target: preferred.path,
+      reason: 'Agent instruction file exists but does not contain the managed DistributionOS block.',
+      recommendedBlock,
+    };
+  }
+
+  if (currentBlock.trim() === recommendedBlock.trim()) {
+    return {
+      action: 'none',
+      target: preferred.path,
+      reason: 'Managed DistributionOS bootstrap block is already current.',
+      recommendedBlock,
+    };
+  }
+
+  return {
+    action: 'update',
+    target: preferred.path,
+    reason: 'Managed DistributionOS bootstrap block exists but differs from the current recommendation.',
+    recommendedBlock,
+  };
+}
+
+export function buildFallbackMcpInstructions(appId) {
+  return [
+    `App ID: ${appId}`,
+    `DistributionOS MCP server: ${MCP_SERVER_URL}`,
+    'Use OAuth sign-in when prompted, then call get_agent_instructions and submit_initialization_context.',
+    'If OAuth is unavailable, create an app-scoped write API key in DistributionOS and expose it only as DISTRIBUTIONOS_API_KEY for the command invocation.',
+    'Never write the API key into AGENTS.md, CLAUDE.md, README, committed MCP config, or any tracked file.',
+  ];
+}
+
+function shellToken(value) {
+  if (/^[a-zA-Z0-9._:-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}