@plainconceptsplatform/agent-harness 3.3.0 → 3.4.1

package/cli/utils/copy.js

@@ -1,134 +1,134 @@
-import fse from 'fs-extra'
-import path from 'path'
-import { canUpdateManagedFile, hashComparableFile, readUpdateManifest, recordManagedFile, writeUpdateManifest } from './update-manifest.js'
-
-// Folders never copied (skills handled separately by installSkills, .bootstrap is internal tooling)
-const ALWAYS_EXCLUDE = ['.bootstrap', 'skills', 'node_modules']
-
-// Files never overwritten even with forceOverwrite: user owns these.
-// The CLI ships templates, but init / the wizard / the user populate them
-// with project-specific content. Overwriting on update would destroy user work.
-const NEVER_OVERWRITE = [
-  `openspec${path.sep}config.yaml`,
-  'opencode.jsonc',
-]
-
-const MARKER_COMMANDS = new Set(['.opencode/commands/ops-review.md', '.opencode/commands/ops-backlog.md'])
-
-// Where a project may legitimately keep the doc instead of the repository root.
-// Foundations puts both under ai/, and projects that follow it point their own
-// AGENTS.md there.
-const ROOT_DOCS = new Set(['ARCHITECTURE.md', 'DESIGN.md'])
-const ALTERNATE_DOC_DIRS = ['ai', 'docs']
-
-// Seeding the "NOT GENERATED YET, run /make-architecture" placeholder next to a
-// real architecture document is worse than seeding nothing: pc-make-guardrails
-// reads the root file as its primary source, and an agent that finds the
-// placeholder there concludes the project has no architecture written down.
-async function documentedElsewhere(destDir, fileName) {
-  if (!ROOT_DOCS.has(fileName)) return false
-  for (const directory of ALTERNATE_DOC_DIRS) {
-    if (await fse.pathExists(path.join(destDir, directory, fileName))) return true
-  }
-  return false
-}
-
-const MANAGED_DIRS = ['.opencode/plugins/', '.opencode/scripts/']
-
-function isTemplateTest(relativePath) {
-  const normalized = relativePath.split(path.sep).join('/')
-  return MANAGED_DIRS.some(dir => normalized.startsWith(dir)) && normalized.endsWith('.test.js')
-}
-
-export function isManagedContentPath(relativePath) {
-  const normalized = relativePath.split(path.sep).join('/')
-  if (MANAGED_DIRS.some(dir => normalized.startsWith(dir))) return true
-  if (normalized.startsWith('.opencode/commands/') && !MARKER_COMMANDS.has(normalized)) return true
-  return normalized === 'openspec/specs/.gitkeep' || normalized === 'openspec/changes/archive/.gitkeep'
-}
-
-/**
- * Copy content/ directory to destination.
- * Excludes:
- *   - .agents/skills and .opencode/skills (handled separately)
- *   - .bootstrap (internal tooling)
- *   - node_modules
- *   - DESIGN.md and ARCHITECTURE.md if ctx says they already exist (preserve user's files)
- * @param {string} contentDir - absolute path to content/
- * @param {string} destDir - absolute path to destination (project root)
- * @param {'azure'|'github'} platform
- * @param {{ hasDesign?: boolean, hasArchitecture?: boolean, updateMode?: boolean }} ctx
- */
-export async function copyContent(contentDir, destDir, platform, ctx = {}) {
-  const manifest = ctx.updateMode ? await readUpdateManifest(destDir) : null
-  await fse.copy(contentDir, destDir, {
-    overwrite: ctx.updateMode || ctx.forceOverwrite || false,
-    filter: async (src) => {
-      const rel = path.relative(contentDir, src)
-      const parts = rel.split(path.sep)
-      if (parts.some(part => ALWAYS_EXCLUDE.includes(part))) return false
-      if (isTemplateTest(rel)) return false
-      if (ctx.hasDesign && rel === 'DESIGN.md') return false
-      if (ctx.hasArchitecture && rel === 'ARCHITECTURE.md') return false
-      if (await documentedElsewhere(destDir, rel)) return false
-      // User-owned config files are never overwritten, even with forceOverwrite.
-      // The update command calls writeModelsToConfigs separately to set the
-      // model field in opencode.jsonc without destroying user additions.
-      if (NEVER_OVERWRITE.includes(rel)) return false
-      if (!ctx.updateMode) return true
-
-      const stat = await fse.stat(src)
-      if (stat.isDirectory()) return true
-      if (!isManagedContentPath(rel)) {
-        return !(await fse.pathExists(path.join(destDir, rel)))
-      }
-      return canUpdateManagedFile(rel, destDir, manifest)
-    },
-  })
-}
-
-export async function recordManagedContent(contentDir, destDir, { updateMode = false } = {}) {
-  const manifest = await readUpdateManifest(destDir)
-
-  async function walk(directory) {
-    for (const entry of await fse.readdir(directory, { withFileTypes: true })) {
-      const sourcePath = path.join(directory, entry.name)
-      const relativePath = path.relative(contentDir, sourcePath)
-      if (entry.isDirectory()) {
-        await walk(sourcePath)
-        continue
-      }
-      if (isTemplateTest(relativePath)) continue
-      if (!isManagedContentPath(relativePath)) continue
-
-      const destinationPath = path.join(destDir, relativePath)
-      if (!await fse.pathExists(destinationPath)) continue
-      // Comparable, not raw: this runs after the patchers, so a managed file's
-      // destination never equals its source byte for byte once anything has
-      // been injected into a marker pair. Comparing raw hashes here meant no
-      // entry was ever recorded for those files, which left them permanently
-      // indistinguishable from files a project had edited by hand.
-      const sourceHash = await hashComparableFile(sourcePath)
-      const destinationHash = await hashComparableFile(destinationPath)
-      const manifestPath = relativePath.split(path.sep).join('/')
-      const previousHash = manifest.files?.[manifestPath]
-      if (!updateMode || destinationHash === sourceHash || destinationHash === previousHash) {
-        await recordManagedFile(manifest, relativePath, sourcePath)
-      }
-    }
-  }
-
-  await walk(contentDir)
-  await writeUpdateManifest(manifest, destDir)
-}
-
-export async function findAiFiles(dir, files) {
-  const found = []
-  for (const file of files) {
-    const fullPath = path.join(dir, file)
-    if (await fse.pathExists(fullPath)) {
-      found.push(fullPath)
-    }
-  }
-  return found
-}
+import fse from 'fs-extra'
+import path from 'path'
+import { canUpdateManagedFile, hashComparableFile, readUpdateManifest, recordManagedFile, writeUpdateManifest } from './update-manifest.js'
+
+// Folders never copied (skills handled separately by installSkills, .bootstrap is internal tooling)
+const ALWAYS_EXCLUDE = ['.bootstrap', 'skills', 'node_modules']
+
+// Files never overwritten even with forceOverwrite: user owns these.
+// The CLI ships templates, but init / the wizard / the user populate them
+// with project-specific content. Overwriting on update would destroy user work.
+const NEVER_OVERWRITE = [
+  `openspec${path.sep}config.yaml`,
+  'opencode.jsonc',
+]
+
+const MARKER_COMMANDS = new Set(['.opencode/commands/ops-review.md', '.opencode/commands/ops-backlog.md'])
+
+// Where a project may legitimately keep the doc instead of the repository root.
+// Foundations puts both under ai/, and projects that follow it point their own
+// AGENTS.md there.
+const ROOT_DOCS = new Set(['ARCHITECTURE.md', 'DESIGN.md'])
+const ALTERNATE_DOC_DIRS = ['ai', 'docs']
+
+// Seeding the "NOT GENERATED YET, run /make-architecture" placeholder next to a
+// real architecture document is worse than seeding nothing: pc-make-guardrails
+// reads the root file as its primary source, and an agent that finds the
+// placeholder there concludes the project has no architecture written down.
+async function documentedElsewhere(destDir, fileName) {
+  if (!ROOT_DOCS.has(fileName)) return false
+  for (const directory of ALTERNATE_DOC_DIRS) {
+    if (await fse.pathExists(path.join(destDir, directory, fileName))) return true
+  }
+  return false
+}
+
+const MANAGED_DIRS = ['.opencode/plugins/', '.opencode/scripts/']
+
+function isTemplateTest(relativePath) {
+  const normalized = relativePath.split(path.sep).join('/')
+  return MANAGED_DIRS.some(dir => normalized.startsWith(dir)) && normalized.endsWith('.test.js')
+}
+
+export function isManagedContentPath(relativePath) {
+  const normalized = relativePath.split(path.sep).join('/')
+  if (MANAGED_DIRS.some(dir => normalized.startsWith(dir))) return true
+  if (normalized.startsWith('.opencode/commands/') && !MARKER_COMMANDS.has(normalized)) return true
+  return normalized === 'openspec/specs/.gitkeep' || normalized === 'openspec/changes/archive/.gitkeep'
+}
+
+/**
+ * Copy content/ directory to destination.
+ * Excludes:
+ *   - .agents/skills and .opencode/skills (handled separately)
+ *   - .bootstrap (internal tooling)
+ *   - node_modules
+ *   - DESIGN.md and ARCHITECTURE.md if ctx says they already exist (preserve user's files)
+ * @param {string} contentDir - absolute path to content/
+ * @param {string} destDir - absolute path to destination (project root)
+ * @param {'azure'|'github'} platform
+ * @param {{ hasDesign?: boolean, hasArchitecture?: boolean, updateMode?: boolean }} ctx
+ */
+export async function copyContent(contentDir, destDir, platform, ctx = {}) {
+  const manifest = ctx.updateMode ? await readUpdateManifest(destDir) : null
+  await fse.copy(contentDir, destDir, {
+    overwrite: ctx.updateMode || ctx.forceOverwrite || false,
+    filter: async (src) => {
+      const rel = path.relative(contentDir, src)
+      const parts = rel.split(path.sep)
+      if (parts.some(part => ALWAYS_EXCLUDE.includes(part))) return false
+      if (isTemplateTest(rel)) return false
+      if (ctx.hasDesign && rel === 'DESIGN.md') return false
+      if (ctx.hasArchitecture && rel === 'ARCHITECTURE.md') return false
+      if (await documentedElsewhere(destDir, rel)) return false
+      // User-owned config files are never overwritten, even with forceOverwrite.
+      // The update command calls writeModelsToConfigs separately to set the
+      // model field in opencode.jsonc without destroying user additions.
+      if (NEVER_OVERWRITE.includes(rel)) return false
+      if (!ctx.updateMode) return true
+
+      const stat = await fse.stat(src)
+      if (stat.isDirectory()) return true
+      if (!isManagedContentPath(rel)) {
+        return !(await fse.pathExists(path.join(destDir, rel)))
+      }
+      return canUpdateManagedFile(rel, destDir, manifest)
+    },
+  })
+}
+
+export async function recordManagedContent(contentDir, destDir, { updateMode = false } = {}) {
+  const manifest = await readUpdateManifest(destDir)
+
+  async function walk(directory) {
+    for (const entry of await fse.readdir(directory, { withFileTypes: true })) {
+      const sourcePath = path.join(directory, entry.name)
+      const relativePath = path.relative(contentDir, sourcePath)
+      if (entry.isDirectory()) {
+        await walk(sourcePath)
+        continue
+      }
+      if (isTemplateTest(relativePath)) continue
+      if (!isManagedContentPath(relativePath)) continue
+
+      const destinationPath = path.join(destDir, relativePath)
+      if (!await fse.pathExists(destinationPath)) continue
+      // Comparable, not raw: this runs after the patchers, so a managed file's
+      // destination never equals its source byte for byte once anything has
+      // been injected into a marker pair. Comparing raw hashes here meant no
+      // entry was ever recorded for those files, which left them permanently
+      // indistinguishable from files a project had edited by hand.
+      const sourceHash = await hashComparableFile(sourcePath)
+      const destinationHash = await hashComparableFile(destinationPath)
+      const manifestPath = relativePath.split(path.sep).join('/')
+      const previousHash = manifest.files?.[manifestPath]
+      if (!updateMode || destinationHash === sourceHash || destinationHash === previousHash) {
+        await recordManagedFile(manifest, relativePath, sourcePath)
+      }
+    }
+  }
+
+  await walk(contentDir)
+  await writeUpdateManifest(manifest, destDir)
+}
+
+export async function findAiFiles(dir, files) {
+  const found = []
+  for (const file of files) {
+    const fullPath = path.join(dir, file)
+    if (await fse.pathExists(fullPath)) {
+      found.push(fullPath)
+    }
+  }
+  return found
+}

package/cli/utils/exec-spinner.js

@@ -1,47 +1,47 @@
-import chalk from 'chalk'
-import ora from 'ora'
-
-// ── Screen / step state ──────────────────────────────────────────────────────
-
-const previousSteps = [];    // up to 2 completed steps, each is an array of lines
-let currentStepLines = [];   // lines accumulated in the current step
-let stepSpinner = null;      // ora spinner shown while step is working
-
-export function appendLine(line) {
-  currentStepLines.push(line);
-}
-
-export function stopSpinner() {
-  if (stepSpinner) {
-    stepSpinner.stop();
-    stepSpinner = null;
-  }
-}
-
-export function startSpinner(text = 'working...') {
-  stopSpinner();
-  stepSpinner = ora({ text: chalk.dim(text), color: 'red' }).start();
-}
-
-export function redraw() {
-  if (process.stdout.isTTY) console.clear();
-
-  // Show up to 2 previous steps dimmed
-  for (const stepLines of previousSteps) {
-    for (const line of stepLines) {
-      process.stdout.write(`${chalk.dim(line)}\n`);
-    }
-    process.stdout.write('\n');
-  }
-
-  // Current step output
-  for (const line of currentStepLines) {
-    process.stdout.write(`${line}\n`);
-  }
-}
-
-export function rotateStep() {
-  previousSteps.push(currentStepLines);
-  if (previousSteps.length > 2) previousSteps.shift();
-  currentStepLines = [];
-}
+import chalk from 'chalk'
+import ora from 'ora'
+
+// ── Screen / step state ──────────────────────────────────────────────────────
+
+const previousSteps = [];    // up to 2 completed steps, each is an array of lines
+let currentStepLines = [];   // lines accumulated in the current step
+let stepSpinner = null;      // ora spinner shown while step is working
+
+export function appendLine(line) {
+  currentStepLines.push(line);
+}
+
+export function stopSpinner() {
+  if (stepSpinner) {
+    stepSpinner.stop();
+    stepSpinner = null;
+  }
+}
+
+export function startSpinner(text = 'working...') {
+  stopSpinner();
+  stepSpinner = ora({ text: chalk.dim(text), color: 'red' }).start();
+}
+
+export function redraw() {
+  if (process.stdout.isTTY) console.clear();
+
+  // Show up to 2 previous steps dimmed
+  for (const stepLines of previousSteps) {
+    for (const line of stepLines) {
+      process.stdout.write(`${chalk.dim(line)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Current step output
+  for (const line of currentStepLines) {
+    process.stdout.write(`${line}\n`);
+  }
+}
+
+export function rotateStep() {
+  previousSteps.push(currentStepLines);
+  if (previousSteps.length > 2) previousSteps.shift();
+  currentStepLines = [];
+}

package/cli/utils/exec.js

@@ -1,134 +1,134 @@
-import chalk from 'chalk'
-import { execa } from 'execa'
-import ora from 'ora'
-import { appendLine, redraw, rotateStep, startSpinner, stopSpinner } from './exec-spinner.js'
-import { MARKERS } from './terminal.js';
-
-// ── Public API ───────────────────────────────────────────────────────────────
-
-/**
- * Run a shell command with a spinner.
- * Returns { success, stdout, stderr }
- */
-export async function run(command, args = [], { label, cwd = process.cwd() } = {}) {
-  const spinner = ora(label ?? `${command} ${args.join(' ')}`).start();
-  try {
-    const result = await execa(command, args, { cwd, reject: false });
-    if (result.exitCode === 0) {
-      spinner.succeed();
-    } else {
-      spinner.fail();
-    }
-    return { success: result.exitCode === 0, stdout: result.stdout, stderr: result.stderr };
-  } catch (err) {
-    spinner.fail();
-    return { success: false, stdout: '', stderr: err.message };
-  }
-}
-
-/**
- * Check if a command is available on PATH.
- * Returns true/false.
- */
-export async function commandExists(command) {
-  try {
-    const result = await execa(command, ['--version'], { reject: false });
-    return result.exitCode === 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Print a section header, clears screen, shows previous step dimmed, starts new step.
- */
-export function header(text) {
-  rotateStep();
-
-  const line1 = '';
-  const line2 = chalk.bold.hex('#fe3d57')(`━━ ${text}`);
-  const line3 = '';
-
-  appendLine(line1);
-  appendLine(line2);
-  appendLine(line3);
-
-  redraw();
-
-  startSpinner('working...');
-}
-
-/**
- * Restart the step spinner after prompts or logs.
- */
-export function loading(text = 'working...') {
-  startSpinner(text);
-}
-
-/**
- * Print a success line.
- */
-export function success(text) {
-  stopSpinner();
-  const line = chalk.green(`${MARKERS.OK_PREFIX}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print a warning line.
- */
-export function warn(text) {
-  stopSpinner();
-  const line = chalk.yellow(`${MARKERS.WARN_PREFIX}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print an error line.
- */
-export function error(text) {
-  stopSpinner();
-  const line = chalk.red(`${MARKERS.ERROR_PREFIX}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print an info line.
- */
-export function info(text) {
-  stopSpinner();
-  const line = chalk.dim(`${MARKERS.EMPTY}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print an action prompt line (white bold, requires user interaction).
- */
-export function prompt(text) {
-  stopSpinner();
-  const line = chalk.bold(`${MARKERS.EMPTY}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print a code block.
- */
-export function code(lines) {
-  stopSpinner();
-  appendLine('');
-  console.log();
-  for (const line of lines) {
-    const formatted = chalk.bgGray.white(
-      `${MARKERS.EMPTY}${line}${MARKERS.EMPTY}`,
-    );
-    appendLine(formatted);
-    console.log(formatted);
-  }
-  appendLine('');
-  console.log();
-}
+import chalk from 'chalk'
+import { execa } from 'execa'
+import ora from 'ora'
+import { appendLine, redraw, rotateStep, startSpinner, stopSpinner } from './exec-spinner.js'
+import { MARKERS } from './terminal.js';
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Run a shell command with a spinner.
+ * Returns { success, stdout, stderr }
+ */
+export async function run(command, args = [], { label, cwd = process.cwd() } = {}) {
+  const spinner = ora(label ?? `${command} ${args.join(' ')}`).start();
+  try {
+    const result = await execa(command, args, { cwd, reject: false });
+    if (result.exitCode === 0) {
+      spinner.succeed();
+    } else {
+      spinner.fail();
+    }
+    return { success: result.exitCode === 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (err) {
+    spinner.fail();
+    return { success: false, stdout: '', stderr: err.message };
+  }
+}
+
+/**
+ * Check if a command is available on PATH.
+ * Returns true/false.
+ */
+export async function commandExists(command) {
+  try {
+    const result = await execa(command, ['--version'], { reject: false });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Print a section header, clears screen, shows previous step dimmed, starts new step.
+ */
+export function header(text) {
+  rotateStep();
+
+  const line1 = '';
+  const line2 = chalk.bold.hex('#fe3d57')(`━━ ${text}`);
+  const line3 = '';
+
+  appendLine(line1);
+  appendLine(line2);
+  appendLine(line3);
+
+  redraw();
+
+  startSpinner('working...');
+}
+
+/**
+ * Restart the step spinner after prompts or logs.
+ */
+export function loading(text = 'working...') {
+  startSpinner(text);
+}
+
+/**
+ * Print a success line.
+ */
+export function success(text) {
+  stopSpinner();
+  const line = chalk.green(`${MARKERS.OK_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print a warning line.
+ */
+export function warn(text) {
+  stopSpinner();
+  const line = chalk.yellow(`${MARKERS.WARN_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an error line.
+ */
+export function error(text) {
+  stopSpinner();
+  const line = chalk.red(`${MARKERS.ERROR_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an info line.
+ */
+export function info(text) {
+  stopSpinner();
+  const line = chalk.dim(`${MARKERS.EMPTY}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an action prompt line (white bold, requires user interaction).
+ */
+export function prompt(text) {
+  stopSpinner();
+  const line = chalk.bold(`${MARKERS.EMPTY}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print a code block.
+ */
+export function code(lines) {
+  stopSpinner();
+  appendLine('');
+  console.log();
+  for (const line of lines) {
+    const formatted = chalk.bgGray.white(
+      `${MARKERS.EMPTY}${line}${MARKERS.EMPTY}`,
+    );
+    appendLine(formatted);
+    console.log(formatted);
+  }
+  appendLine('');
+  console.log();
+}