@distributionos/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # DistributionOS CLI
 
-Local installer for connecting an app repo to DistributionOS.
+Installer for connecting an app repo to DistributionOS.
 
 ```bash
 npx @distributionos/cli setup --app <appId>
@@ -8,11 +8,11 @@ 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
-```
+Agents that support installable skills can also load the public DistributionOS agent skill before using the CLI:
+
+https://github.com/lawfan1026/distributionos-agent-skill
+
+The CLI remains the default setup path. The skill is a public agent-readable guide for when to use the CLI, MCP, API fallback, analytics install, verification, and implementation reporting.
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distributionos/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "DistributionOS repo setup CLI for agent onboarding and first-party analytics.",
   "homepage": "https://distributionos.dev",
   "repository": {

package/src/api.js

@@ -1,12 +1,21 @@
 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 };
-  }
+import { getStoredCredential } from './auth-store.js';
+import { isCredentialFresh, refreshOAuthCredential } from './oauth.js';
+
+export class DistributionOsApiError extends Error {
+  constructor(message, { status = 0, code = null } = {}) {
+    super(message);
+    this.name = 'DistributionOsApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+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;
 }
 
@@ -39,48 +48,69 @@ export async function fetchDistributionOsSetupContext(input) {
     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,
-  };
-}
+  });
+  if (!token || input.noFetch) {
+    return {
+      status: input.noFetch ? 'skipped' : 'not_authenticated',
+      tokenName: token?.name ?? null,
+      access: {
+        allowed: false,
+        reason: input.noFetch ? 'remote_fetch_skipped' : 'not_authenticated',
+        billingUrl: `${normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE)}/dashboard/account/billing`,
+      },
+      usage: null,
+      instructions: null,
+      analyticsContract: null,
+      errors: [],
+    };
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const errors = [];
+  let subscriptionRequired = false;
+  const capture = (label) => (error) => {
+    if (error instanceof DistributionOsApiError && (error.status === 402 || error.code === 'SUBSCRIPTION_REQUIRED')) {
+      subscriptionRequired = true;
+    }
+    errors.push(`${label} failed: ${error.message}`);
+    return null;
+  };
+
+  const [instructions, analyticsContract, usage] = await Promise.all([
+    fetchJson({
+      fetchImpl: input.fetch,
+      apiBase,
+      token: token.value,
+      path: `/api/v1/apps/${encodeURIComponent(input.appId)}/agent/instructions`,
+    }).catch(capture('Agent instructions fetch')),
+    fetchJson({
+      fetchImpl: input.fetch,
+      apiBase,
+      token: token.value,
+      path: `/api/v1/apps/${encodeURIComponent(input.appId)}/analytics/contract`,
+    }).catch(capture('Analytics contract fetch')),
+    fetchJson({
+      fetchImpl: input.fetch,
+      apiBase,
+      token: token.value,
+      path: `/api/v1/apps/${encodeURIComponent(input.appId)}/usage`,
+    }).catch(capture('Usage fetch')),
+  ]);
+
+  return {
+    status: errors.length === 0 ? 'fetched' : 'partial',
+    tokenName: token.name,
+    access: {
+      allowed: !subscriptionRequired,
+      reason: subscriptionRequired ? 'subscription_required' : errors.length === 0 ? 'active' : 'partial',
+      billingUrl: `${apiBase}/dashboard/account/billing`,
+    },
+    usage,
+    instructions,
+    analyticsContract,
+    errors,
+  };
+}
 
 export async function ensureAnalyticsSite(input) {
   const token = await resolveAuthToken({
@@ -198,11 +228,14 @@ async function fetchJson({ fetchImpl, apiBase, token, path }) {
     },
   });
   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;
-}
+  if (!response.ok || body?.success === false) {
+    throw new DistributionOsApiError(body?.error || `HTTP ${response.status}`, {
+      status: response.status,
+      code: body?.code ?? null,
+    });
+  }
+  return body?.data ?? body;
+}
 
 function normalizeApiBase(value) {
   return String(value || DEFAULT_API_BASE).replace(/\/+$/, '');

package/src/cli.js

@@ -157,14 +157,19 @@ export async function runCli(argv, runtime) {
     args.apply = true;
   }
 
-  if (args.yes) {
-    args.apply = true;
-  }
-
-  if (args.apply && plan.repo.git.dirty && !args.allowDirty) {
-    stderr.write('Refusing to apply changes to a dirty worktree. Commit/stash changes or pass --allow-dirty.\n');
-    return 1;
-  }
+  if (args.yes) {
+    args.apply = true;
+  }
+
+  if (args.apply && hasRemoteAccessBlock(plan)) {
+    stderr.write(formatRemoteAccessBlock(plan));
+    return 1;
+  }
+
+  if (args.apply && plan.repo.git.dirty && !args.allowDirty) {
+    stderr.write('Refusing to apply changes to a dirty worktree. Commit/stash changes or pass --allow-dirty.\n');
+    return 1;
+  }
 
   if (args.apply && !args.skipAnalytics) {
     const ensured = await ensureAnalyticsSite({
@@ -230,12 +235,26 @@ export async function runCli(argv, runtime) {
   }
 }
 
-function hasBlockingApplyFailure(validation, inspection) {
-  return validation.some((result) => result.introducedFailure) ||
-    inspection.some((result) => result.status === 'failed');
-}
-
-export function parseArgs(rawArgs) {
+function hasBlockingApplyFailure(validation, inspection) {
+  return validation.some((result) => result.introducedFailure) ||
+    inspection.some((result) => result.status === 'failed');
+}
+
+function hasRemoteAccessBlock(plan) {
+  return plan.remote?.access?.reason === 'subscription_required';
+}
+
+function formatRemoteAccessBlock(plan) {
+  const billingUrl = plan.remote?.access?.billingUrl ?? `${plan.apiBase ?? DEFAULT_API_BASE}/dashboard/account/billing`;
+  return [
+    'DistributionOS setup requires an active Builder or Distributor subscription before applying changes.',
+    `Manage billing: ${billingUrl}`,
+    'No files were changed.',
+    '',
+  ].join('\n');
+}
+
+export function parseArgs(rawArgs) {
   const parsed = {
     command: null,
     appId: null,
@@ -325,7 +344,8 @@ function helpText() {
     '  distributionos verify --app <appId> --url <liveUrl> [--content-id <id>]',
     '  distributionos report-implementation --app <appId> --artifact <artifactId> [--url <liveUrl>] [--summary <text>]',
     '',
-    'Default mode prints a dry-run plan. Interactive terminals can confirm the plan before mutation; non-interactive runs need --apply or --yes.',
+    'Default mode reviews the setup plan without changing files. Run again with --apply after the plan looks right.',
+    'If the repo has existing uncommitted changes, commit/stash first or use --allow-dirty when you recognize them.',
     '',
     'Authentication:',
     '  Happy path uses DistributionOS MCP OAuth and stores app-scoped credentials outside the repo.',

package/src/constants.js

@@ -1,13 +1,13 @@
-import { readFileSync } from 'node:fs';
-
-const cliPackageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-
-export const CLI_PACKAGE_NAME = '@distributionos/cli';
-export const CLI_LOCAL_VERSION = typeof cliPackageJson.version === 'string' ? cliPackageJson.version : '0.0.0-local';
-export const DEFAULT_API_BASE = 'https://distributionos.dev';
+import { readFileSync } from 'node:fs';
+
+const cliPackageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+export const CLI_PACKAGE_NAME = '@distributionos/cli';
+export const CLI_LOCAL_VERSION = typeof cliPackageJson.version === 'string' ? cliPackageJson.version : '0.0.0-local';
+export const DEFAULT_API_BASE = 'https://distributionos.dev';
 export const MCP_SERVER_URL = 'https://distributionos.dev/api/mcp';
-export const CURRENT_BOOTSTRAP_VERSION = '2026.06.13';
-export const CURRENT_ANALYTICS_CONTRACT_VERSION = '2026.06.13';
+export const CURRENT_BOOTSTRAP_VERSION = '2026.06.14';
+export const CURRENT_ANALYTICS_CONTRACT_VERSION = '2026.06.14';
 
 export const TOKEN_ENV_NAMES = [
   'DISTRIBUTIONOS_API_KEY',

package/src/oauth.js

@@ -27,11 +27,14 @@ export async function loginWithOAuth(options) {
       state,
     });
 
-    options.stdout?.write([
-      'Open this DistributionOS authorization URL:',
-      authorizeUrl,
-      '',
-    ].join('\n'));
+    options.stdout?.write([
+      'Open this DistributionOS authorization URL:',
+      authorizeUrl,
+      '',
+      'Keep this terminal running until the browser says the CLI is connected.',
+      'If the browser opens a failed connection page, press Ctrl+C here and rerun with --no-open, then paste the full printed URL into your browser.',
+      '',
+    ].join('\n'));
     if (options.openBrowser !== false) openUrl(authorizeUrl);
 
     const authResult = await callback.waitForCallback();
@@ -204,18 +207,28 @@ async function createCallbackServer() {
   };
 }
 
-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,
+export function getOpenUrlCommand(url, platform = process.platform) {
+  const command = platform === 'win32'
+    ? 'cmd'
+    : platform === 'darwin'
+      ? 'open'
+      : 'xdg-open';
+  const args = platform === 'win32'
+    ? ['/c', 'start', '""', quoteWindowsStartUrl(url)]
+    : [url];
+  return { command, args };
+}
+
+function quoteWindowsStartUrl(url) {
+  const safeUrl = String(url).replace(/"/g, '%22');
+  return `"${safeUrl}"`;
+}
+
+function openUrl(url) {
+  const { command, args } = getOpenUrlCommand(url);
+  try {
+    const child = spawn(command, args, {
+      detached: true,
       stdio: 'ignore',
       windowsHide: true,
     });

package/src/plan.js

@@ -89,11 +89,11 @@ function sanitizePackageJson(packageJson) {
 
 export function formatPlanText(plan) {
   const lines = [
-    'DistributionOS CLI setup plan',
-    `App: ${plan.appId}`,
-    plan.mode === 'apply'
-      ? 'Mode: apply'
-      : 'Mode: dry-run (no files changed)',
+    'DistributionOS CLI setup plan',
+    `App: ${plan.appId}`,
+    plan.mode === 'apply'
+      ? 'Step: apply approved setup'
+      : 'Step: review setup plan (no files changed yet)',
     `Package: ${plan.packageName}`,
     `Future command: ${plan.futureCommand}`,
     `Local command: ${plan.localCommand}`,
@@ -106,11 +106,12 @@ export function formatPlanText(plan) {
     `- 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}`),
-    '',
+    '',
+    'DistributionOS access',
+    remoteSummary(plan),
+    ...usageSummary(plan.remote.usage),
+    ...plan.remote.errors.map(error => `- ${error}`),
+    '',
     'Planned changes',
     `1. Agent bootstrap: ${plan.bootstrap.action} ${plan.bootstrap.target}`,
     `   ${plan.bootstrap.reason}`,
@@ -138,12 +139,47 @@ export function formatPlanText(plan) {
     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`;
-}
+  if (plan.warnings.length > 0) {
+    lines.push('', 'Warnings', ...plan.warnings.map(item => `- ${item}`));
+  }
+
+  lines.push(...nextStepLines(plan));
+
+  return `${lines.join('\n')}\n`;
+}
+
+function nextStepLines(plan) {
+  if (plan.mode === 'apply') return [];
+
+  const applyCommand = `${plan.futureCommand} --apply`;
+  const lines = [
+    '',
+    'Next step: install approved setup',
+  ];
+
+  if (plan.repo.git.dirty) {
+    lines.push(
+      'This repo has existing uncommitted changes.',
+      'Recommended: commit or stash those changes, then run:',
+      `  ${applyCommand}`,
+      '',
+      'If you recognize the existing changes and want DistributionOS to edit only its managed files, run:',
+      `  ${applyCommand} --allow-dirty`,
+    );
+  } else {
+    lines.push(
+      'If the planned changes look right, run:',
+      `  ${applyCommand}`,
+    );
+  }
+
+  lines.push(
+    '',
+    'DistributionOS expects to edit only the managed agent instruction block and the supported analytics layout. Review git diff before committing or deploying.',
+  );
+
+  return lines;
+}
 
 function buildAnalyticsPlan({ analyticsContract, repo, instructionPackVersion }) {
   const layoutTarget = selectAnalyticsLayoutTarget(repo);
@@ -209,11 +245,14 @@ function selectAnalyticsLayoutTarget(repo) {
   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.');
-  }
+function buildWarnings({ repo, remote }) {
+  const warnings = [];
+  if (remote.access?.reason === 'subscription_required') {
+    warnings.push('Active Builder or Distributor subscription required before applying setup.');
+  }
+  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.');
   }
@@ -237,15 +276,36 @@ function buildValidationPlan(repo) {
   };
 }
 
-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 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.`;
+  }
+  if (plan.remote.status === 'skipped') {
+    return '- Remote fetch skipped. The setup plan used local fallback instructions and did not call DistributionOS APIs.';
+  }
+  return '- No OAuth or env token found. The setup plan used local fallback instructions and did not call DistributionOS APIs.';
+}
+
+function usageSummary(usage) {
+  if (!usage) return [];
+  const plan = usage.plan
+    ? `- Plan: ${usage.plan.name}${usage.plan.priceLabel ? ` (${usage.plan.priceLabel})` : ''}`
+    : '- Plan: active account access';
+  const monthly = usage.monthly ?? {};
+  return [
+    plan,
+    `- Monthly caps: briefs ${meterText(monthly.brief_handoffs)}, images ${meterText(monthly.image_generations)}, research ${meterText(monthly.fresh_research_runs)}`,
+  ];
+}
+
+function meterText(value) {
+  if (!value) return 'unknown';
+  const limit = value.limit < 0 ? 'unlimited' : value.limit;
+  return `${value.used ?? 0}/${limit}`;
+}
 
 function analyticsSummary(analytics) {
   if (analytics.status === 'enabled') {