@openprd/cli 0.1.0

package/src/self-update.js

@@ -0,0 +1,329 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_SELF_UPDATE_SOURCE = 'git+https://github.com/mileson/openprd.git';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_PACKAGE_ROOT = path.resolve(MODULE_DIR, '..');
+
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+export function formatCommand(command, args = []) {
+  return [command, ...args].map(shellQuote).join(' ');
+}
+
+async function readPackageInfo(packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const packageJsonPath = path.join(packageRoot, 'package.json');
+  const raw = await fs.readFile(packageJsonPath, 'utf8');
+  const packageJson = JSON.parse(raw);
+  return {
+    name: packageJson.name ?? null,
+    version: packageJson.version ?? null,
+    packageRoot,
+    packageJsonPath,
+  };
+}
+
+async function isLocalSourceCheckout(packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const gitDir = path.join(packageRoot, '.git');
+  return fs.stat(gitDir).then((stat) => stat.isDirectory() || stat.isFile(), () => false);
+}
+
+function runProcess(command, args = [], options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      shell: Boolean(options.shell),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout = `${stdout}${chunk}`.slice(-64000);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-64000);
+    });
+    child.on('error', (error) => {
+      resolve({
+        ok: false,
+        command,
+        args,
+        display: formatCommand(command, args),
+        exitCode: null,
+        stdout,
+        stderr: `${stderr}${error.message}`,
+      });
+    });
+    child.on('close', (exitCode) => {
+      resolve({
+        ok: exitCode === 0,
+        command,
+        args,
+        display: formatCommand(command, args),
+        exitCode,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+async function resolveOpenPrdExecutable(deps = {}) {
+  if (typeof deps.resolveOpenPrdExecutable === 'function') {
+    return deps.resolveOpenPrdExecutable();
+  }
+  const command = process.platform === 'win32' ? 'where openprd' : 'command -v openprd';
+  const result = await runProcess(command, [], { shell: true });
+  const executable = result.stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? null;
+  if (!result.ok || !executable) {
+    return {
+      ok: false,
+      executable: null,
+      command,
+      error: result.stderr.trim() || 'Unable to resolve openprd executable from PATH.',
+    };
+  }
+  return {
+    ok: true,
+    executable,
+    command,
+    error: null,
+  };
+}
+
+function buildSelfUpdatePlan(options = {}) {
+  const source = options.source ?? DEFAULT_SELF_UPDATE_SOURCE;
+  const command = options.packageManager ?? 'npm';
+  const args = ['install', '-g', source];
+  return {
+    source,
+    install: {
+      command,
+      args,
+      display: formatCommand(command, args),
+    },
+  };
+}
+
+function buildProjectRefreshPlan(targetPath, options = {}) {
+  const executable = options.executable ?? 'openprd';
+  const args = options.fleet
+    ? ['fleet', targetPath, '--update-openprd']
+    : ['update', targetPath];
+
+  if (options.fleet && options.maxDepth) {
+    args.push('--max-depth', String(options.maxDepth));
+  }
+  if (options.fleet && options.include) {
+    args.push('--include', String(options.include));
+  }
+  if (options.fleet && options.exclude) {
+    args.push('--exclude', String(options.exclude));
+  }
+  if (options.fleet && options.report) {
+    args.push('--report');
+    if (typeof options.report === 'string') {
+      args.push(options.report);
+    }
+  }
+  if (options.tools) {
+    args.push('--tools', options.tools);
+  }
+  if (options.hookProfile) {
+    args.push('--hook-profile', options.hookProfile);
+  }
+  if (options.force && !options.fleet) {
+    args.push('--force');
+  }
+  if (options.childJson) {
+    args.push('--json');
+  }
+
+  return {
+    mode: options.fleet ? 'fleet' : 'project',
+    targetPath,
+    refresh: {
+      command: executable,
+      args,
+      display: formatCommand(executable, args),
+    },
+  };
+}
+
+export function createSelfUpdateWorkspace(deps = {}) {
+  const runCommand = deps.runCommand ?? runProcess;
+  const packageRoot = deps.packageRoot ?? DEFAULT_PACKAGE_ROOT;
+
+  async function selfUpdateWorkspace(options = {}) {
+    const packageInfo = await (deps.readPackageInfo ?? readPackageInfo)(packageRoot);
+    const localCheckout = await (deps.isLocalSourceCheckout ?? isLocalSourceCheckout)(packageRoot);
+    const plan = buildSelfUpdatePlan(options);
+    const base = {
+      ok: true,
+      action: 'self-update',
+      dryRun: Boolean(options.dryRun),
+      source: plan.source,
+      package: packageInfo,
+      localCheckout,
+      installCommand: plan.install,
+      result: null,
+      resolvedExecutable: null,
+      errors: [],
+      nextActions: [],
+    };
+
+    if (options.dryRun) {
+      return {
+        ...base,
+        skipped: true,
+        skipReason: 'dry-run',
+        nextActions: ['Run without --dry-run to update the OpenPrd CLI.'],
+      };
+    }
+
+    if (localCheckout && !options.allowLocalCheckout) {
+      return {
+        ...base,
+        ok: false,
+        skipped: true,
+        skipReason: 'local-source-checkout',
+        errors: [
+          'This openprd command is running from a local source checkout. Reinstall the global CLI with npm, or use your local development workflow.',
+        ],
+        nextActions: [
+          `Run ${plan.install.display} from outside the source checkout, or update this checkout manually.`,
+        ],
+      };
+    }
+
+    const installResult = await runCommand(plan.install.command, plan.install.args, {
+      cwd: options.cwd ?? packageInfo.packageRoot,
+      env: options.env ?? process.env,
+    });
+    const resolvedExecutable = installResult.ok
+      ? await resolveOpenPrdExecutable(deps)
+      : null;
+
+    return {
+      ...base,
+      ok: installResult.ok && (resolvedExecutable?.ok ?? false),
+      result: installResult,
+      resolvedExecutable,
+      errors: [
+        ...(installResult.ok ? [] : [installResult.stderr.trim() || `Self-update command failed with exit code ${installResult.exitCode}.`]),
+        ...(installResult.ok && !resolvedExecutable?.ok ? [resolvedExecutable?.error ?? 'Unable to resolve updated openprd executable.'] : []),
+      ],
+      nextActions: installResult.ok && !resolvedExecutable?.ok
+        ? ['Check that the global npm bin directory is on PATH, then run openprd update <project>.']
+        : [],
+    };
+  }
+
+  async function upgradeWorkspace(targetPath, options = {}) {
+    const resolvedTarget = path.resolve(targetPath ?? process.cwd());
+    const selfUpdate = await selfUpdateWorkspace(options);
+    const dryRun = Boolean(options.dryRun);
+    const executable = selfUpdate.resolvedExecutable?.executable ?? 'openprd';
+    const refreshPlan = buildProjectRefreshPlan(resolvedTarget, {
+      ...options,
+      executable,
+      childJson: Boolean(options.json),
+    });
+    const base = {
+      ok: true,
+      action: 'upgrade',
+      dryRun,
+      mode: refreshPlan.mode,
+      targetPath: resolvedTarget,
+      selfUpdate,
+      projectRefresh: {
+        ok: true,
+        skipped: false,
+        command: refreshPlan.refresh,
+        result: null,
+        errors: [],
+      },
+      stages: {
+        selfUpdateOk: selfUpdate.ok,
+        projectRefreshOk: true,
+      },
+      errors: [],
+    };
+
+    if (dryRun) {
+      return {
+        ...base,
+        projectRefresh: {
+          ...base.projectRefresh,
+          skipped: true,
+          skipReason: 'dry-run',
+        },
+      };
+    }
+
+    if (!selfUpdate.ok) {
+      return {
+        ...base,
+        ok: false,
+        projectRefresh: {
+          ...base.projectRefresh,
+          ok: false,
+          skipped: true,
+          skipReason: 'self-update-failed',
+          errors: ['Project refresh was not run because self-update did not complete.'],
+        },
+        stages: {
+          selfUpdateOk: false,
+          projectRefreshOk: false,
+        },
+        errors: selfUpdate.errors,
+      };
+    }
+
+    const refreshResult = await runCommand(refreshPlan.refresh.command, refreshPlan.refresh.args, {
+      cwd: options.cwd ?? resolvedTarget,
+      env: options.env ?? process.env,
+    });
+    const projectRefresh = {
+      ok: refreshResult.ok,
+      skipped: false,
+      command: refreshPlan.refresh,
+      result: refreshResult,
+      errors: refreshResult.ok ? [] : [refreshResult.stderr.trim() || `Project refresh failed with exit code ${refreshResult.exitCode}.`],
+    };
+
+    return {
+      ...base,
+      ok: selfUpdate.ok && projectRefresh.ok,
+      projectRefresh,
+      stages: {
+        selfUpdateOk: selfUpdate.ok,
+        projectRefreshOk: projectRefresh.ok,
+      },
+      errors: [
+        ...selfUpdate.errors,
+        ...projectRefresh.errors,
+      ],
+    };
+  }
+
+  return {
+    selfUpdateWorkspace,
+    upgradeWorkspace,
+  };
+}
+
+const defaultWorkspace = createSelfUpdateWorkspace();
+
+export const selfUpdateWorkspace = defaultWorkspace.selfUpdateWorkspace;
+export const upgradeWorkspace = defaultWorkspace.upgradeWorkspace;

package/src/session-binding.js

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { readJson, writeJson } from './fs-utils.js';
+import { timestamp } from './time.js';
+
+const OPENPRD_HARNESS_DIR = path.join('.openprd', 'harness');
+const OPENPRD_HARNESS_REQUIREMENT_GATE = path.join(OPENPRD_HARNESS_DIR, 'requirement-gate.json');
+const OPENPRD_HARNESS_SESSION_BINDINGS_DIR = path.join(OPENPRD_HARNESS_DIR, 'session-bindings');
+
+function normalizeSessionId(sessionId) {
+  const text = String(sessionId ?? '').trim();
+  return text || null;
+}
+
+function sessionBindingPath(projectRoot, sessionId) {
+  const normalized = normalizeSessionId(sessionId);
+  if (!normalized) {
+    return null;
+  }
+  return path.join(
+    projectRoot,
+    OPENPRD_HARNESS_SESSION_BINDINGS_DIR,
+    `${normalized.replace(/[^A-Za-z0-9._-]/g, '_')}.json`,
+  );
+}
+
+async function readLegacyRequirementGate(projectRoot) {
+  return readJson(path.join(projectRoot, OPENPRD_HARNESS_REQUIREMENT_GATE)).catch(() => null);
+}
+
+async function readSessionBinding(projectRoot, sessionId) {
+  const filePath = sessionBindingPath(projectRoot, sessionId);
+  if (!filePath) {
+    return null;
+  }
+  const binding = await readJson(filePath).catch(() => null);
+  return binding ? { ...binding, path: filePath } : null;
+}
+
+async function upsertSessionBinding(projectRoot, sessionId, patch = {}) {
+  const normalized = normalizeSessionId(sessionId);
+  if (!normalized) {
+    return null;
+  }
+  const filePath = sessionBindingPath(projectRoot, normalized);
+  const previous = await readJson(filePath).catch(() => null);
+  const next = {
+    ...(previous ?? {}),
+    version: 1,
+    sessionId: normalized,
+    ...patch,
+    createdAt: previous?.createdAt ?? patch.createdAt ?? timestamp(),
+    updatedAt: patch.updatedAt ?? timestamp(),
+  };
+  await writeJson(filePath, next);
+  return {
+    ...next,
+    path: filePath,
+  };
+}
+
+async function syncSessionBindingFromSnapshot(projectRoot, snapshot, options = {}) {
+  const legacyGate = await readLegacyRequirementGate(projectRoot);
+  const sessionId = normalizeSessionId(options.sessionId ?? legacyGate?.sessionId);
+  if (!sessionId || !snapshot?.versionId) {
+    return null;
+  }
+  return upsertSessionBinding(projectRoot, sessionId, {
+    promptPreview: options.promptPreview ?? legacyGate?.promptPreview ?? null,
+    gateStatus: legacyGate?.status ?? null,
+    gateActive: Boolean(legacyGate?.active),
+    title: snapshot.title ?? null,
+    versionId: snapshot.versionId,
+    digest: snapshot.digest ?? null,
+    workUnitId: snapshot.workUnitId ?? null,
+    targetRoot: options.targetRoot ?? snapshot.targetRoot ?? null,
+    reviewStatus: options.reviewStatus ?? 'pending-confirmation',
+    reviewPath: options.reviewPath ?? options.stableReviewArtifact ?? null,
+    activeReviewPath: options.activeReviewPath ?? options.reviewArtifact ?? null,
+    reviewArtifact: options.reviewArtifact ?? options.activeReviewPath ?? null,
+    stableReviewArtifact: options.stableReviewArtifact ?? options.reviewPath ?? null,
+    changeId: options.preserveChangeId ? (options.changeId ?? null) : null,
+  });
+}
+
+async function syncSessionBindingFromReview(projectRoot, snapshot, options = {}) {
+  const legacyGate = await readLegacyRequirementGate(projectRoot);
+  const sessionId = normalizeSessionId(options.sessionId ?? legacyGate?.sessionId);
+  if (!sessionId || !snapshot?.versionId) {
+    return null;
+  }
+  return upsertSessionBinding(projectRoot, sessionId, {
+    promptPreview: options.promptPreview ?? legacyGate?.promptPreview ?? null,
+    gateStatus: legacyGate?.status ?? null,
+    gateActive: Boolean(legacyGate?.active),
+    title: snapshot.title ?? null,
+    versionId: snapshot.versionId,
+    digest: snapshot.digest ?? null,
+    workUnitId: snapshot.workUnitId ?? null,
+    targetRoot: options.targetRoot ?? snapshot.targetRoot ?? null,
+    reviewStatus: options.reviewStatus ?? null,
+    reviewPath: options.reviewPath ?? options.stableReviewArtifact ?? null,
+    activeReviewPath: options.activeReviewPath ?? options.reviewArtifact ?? null,
+    reviewArtifact: options.reviewArtifact ?? options.activeReviewPath ?? null,
+    stableReviewArtifact: options.stableReviewArtifact ?? options.reviewPath ?? null,
+  });
+}
+
+async function syncSessionBindingFromChange(projectRoot, changeId, options = {}) {
+  const legacyGate = await readLegacyRequirementGate(projectRoot);
+  const sessionId = normalizeSessionId(options.sessionId ?? legacyGate?.sessionId);
+  if (!sessionId || !changeId) {
+    return null;
+  }
+  return upsertSessionBinding(projectRoot, sessionId, {
+    promptPreview: options.promptPreview ?? legacyGate?.promptPreview ?? null,
+    gateStatus: legacyGate?.status ?? null,
+    gateActive: Boolean(legacyGate?.active),
+    title: options.title ?? null,
+    versionId: options.versionId ?? null,
+    digest: options.digest ?? null,
+    workUnitId: options.workUnitId ?? null,
+    targetRoot: options.targetRoot ?? null,
+    reviewStatus: options.reviewStatus ?? null,
+    reviewPath: options.reviewPath ?? options.stableReviewArtifact ?? null,
+    activeReviewPath: options.activeReviewPath ?? options.reviewArtifact ?? null,
+    reviewArtifact: options.reviewArtifact ?? options.activeReviewPath ?? null,
+    stableReviewArtifact: options.stableReviewArtifact ?? options.reviewPath ?? null,
+    changeId,
+  });
+}
+
+export {
+  readLegacyRequirementGate,
+  readSessionBinding,
+  sessionBindingPath,
+  syncSessionBindingFromChange,
+  syncSessionBindingFromReview,
+  syncSessionBindingFromSnapshot,
+  upsertSessionBinding,
+};

package/src/source-inventory.js

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { cjoin, exists } from './fs-utils.js';
+import { timestamp } from './time.js';
+
+const SOURCE_INVENTORY_IGNORE_DIRS = new Set([
+  '.git',
+  '.hg',
+  '.svn',
+  '.openprd',
+  '.openspec',
+  '.next',
+  '.turbo',
+  '.cache',
+  '.env',
+  '.eggs',
+  '.mypy_cache',
+  '.parcel-cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.tox',
+  '.venv',
+  '.vite',
+  '.vscode',
+  'coverage',
+  'dist',
+  'env',
+  'build',
+  'node_modules',
+  'vendor',
+  'venv',
+  '__pycache__',
+]);
+const SOURCE_INVENTORY_EXTENSIONS = new Set([
+  '.cjs',
+  '.css',
+  '.go',
+  '.html',
+  '.java',
+  '.js',
+  '.json',
+  '.jsx',
+  '.kt',
+  '.md',
+  '.mjs',
+  '.php',
+  '.py',
+  '.rb',
+  '.rs',
+  '.scss',
+  '.sh',
+  '.sql',
+  '.swift',
+  '.toml',
+  '.ts',
+  '.tsx',
+  '.vue',
+  '.yaml',
+  '.yml',
+]);
+const SOURCE_INVENTORY_SPECIAL_FILES = new Set([
+  'Dockerfile',
+  'Makefile',
+  'Procfile',
+  'README',
+  'LICENSE',
+  'AGENTS.md',
+  'CLAUDE.md',
+]);
+
+function shouldIgnoreSourceDirectory(name) {
+  const normalized = String(name ?? '').toLowerCase();
+  return SOURCE_INVENTORY_IGNORE_DIRS.has(normalized)
+    || /^\.?venv(?:[-_].*)?$/.test(normalized)
+    || /^env(?:[-_].*)?$/.test(normalized);
+}
+
+function shouldInventorySourceFile(name) {
+  if (SOURCE_INVENTORY_SPECIAL_FILES.has(name)) {
+    return true;
+  }
+  return SOURCE_INVENTORY_EXTENSIONS.has(path.extname(name).toLowerCase());
+}
+
+function compareSourceInventoryEntries(a, b) {
+  const aHidden = a.name.startsWith('.');
+  const bHidden = b.name.startsWith('.');
+  if (aHidden !== bHidden) {
+    return aHidden ? 1 : -1;
+  }
+  if (a.isDirectory() !== b.isDirectory()) {
+    return a.isDirectory() ? -1 : 1;
+  }
+  return a.name.localeCompare(b.name);
+}
+
+function classifyInventoryFile(relativePath) {
+  const lower = relativePath.toLowerCase();
+  const base = path.basename(lower);
+  if (base.includes('test') || base.includes('spec') || lower.includes('/test/') || lower.includes('/tests/')) {
+    return 'test';
+  }
+  if (lower.endsWith('.md') || lower.includes('/docs/') || base === 'readme') {
+    return 'document';
+  }
+  if (['package.json', 'tsconfig.json', 'vite.config.ts', 'next.config.js', 'dockerfile', 'makefile'].includes(base) || lower.endsWith('.yaml') || lower.endsWith('.yml') || lower.endsWith('.toml')) {
+    return 'configuration';
+  }
+  if (lower.includes('/schema/') || lower.endsWith('.sql')) {
+    return 'schema';
+  }
+  return 'implementation';
+}
+
+function sourceLanguage(relativePath) {
+  const ext = path.extname(relativePath).toLowerCase().replace('.', '');
+  if (!ext) {
+    return path.basename(relativePath);
+  }
+  if (['js', 'jsx', 'mjs', 'cjs'].includes(ext)) return 'javascript';
+  if (['ts', 'tsx'].includes(ext)) return 'typescript';
+  if (['yml', 'yaml'].includes(ext)) return 'yaml';
+  if (ext === 'md') return 'markdown';
+  return ext;
+}
+
+async function collectSourceInventory(sourceRoot, options = {}) {
+  const maxDepth = Number(options.maxDepth ?? 6);
+  const maxFiles = Number(options.maxFiles ?? 250);
+  const files = [];
+  const directories = [];
+  const languageBreakdown = {};
+  let truncated = false;
+
+  if (!(await exists(sourceRoot))) {
+    throw new Error(`Missing source root for OpenPrd discovery: ${sourceRoot}`);
+  }
+
+  async function walk(currentDir, depth) {
+    if (files.length >= maxFiles) {
+      truncated = true;
+      return;
+    }
+
+    let entries = [];
+    try {
+      entries = await fs.readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    entries.sort(compareSourceInventoryEntries);
+
+    for (const entry of entries) {
+      if (files.length >= maxFiles) {
+        truncated = true;
+        return;
+      }
+
+      const absolutePath = cjoin(currentDir, entry.name);
+      const relativePath = path.relative(sourceRoot, absolutePath);
+      if (!relativePath || relativePath.startsWith('..')) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        if (shouldIgnoreSourceDirectory(entry.name)) {
+          continue;
+        }
+        directories.push(relativePath);
+        if (depth < maxDepth) {
+          await walk(absolutePath, depth + 1);
+        } else {
+          truncated = true;
+        }
+        continue;
+      }
+
+      if (!entry.isFile() || !shouldInventorySourceFile(entry.name)) {
+        continue;
+      }
+
+      let stats = null;
+      try {
+        stats = await fs.stat(absolutePath);
+      } catch {
+        stats = null;
+      }
+
+      const language = sourceLanguage(relativePath);
+      languageBreakdown[language] = (languageBreakdown[language] ?? 0) + 1;
+      files.push({
+        path: relativePath,
+        kind: classifyInventoryFile(relativePath),
+        language,
+        sizeBytes: stats?.size ?? null,
+      });
+    }
+  }
+
+  await walk(sourceRoot, 0);
+
+  return {
+    version: 1,
+    generatedAt: timestamp(),
+    sourceRoot,
+    summary: {
+      files: files.length,
+      directories: directories.length,
+      truncated,
+      languageBreakdown,
+      topLevelDirectories: [...new Set(directories.map((dir) => dir.split(path.sep)[0]))].slice(0, 30),
+    },
+    files,
+    directories,
+  };
+}
+
+
+export {
+  SOURCE_INVENTORY_IGNORE_DIRS,
+  collectSourceInventory,
+  shouldIgnoreSourceDirectory
+};