@plainconceptsplatform/agent-harness 3.9.0 → 3.11.0

package/cli/utils/agent-color.js

@@ -1,111 +1,111 @@
-/**
- * Deterministic colour for an agent, derived from its name.
- *
- * opencode accepts either a hex value or one of its theme keywords. Two of
- * those keywords are reserved for the primaries so they stay recognisable
- * across every project: build is `primary`, plan is `warning`. Every other
- * agent gets a hex derived from its name, so a `butterfly-engineer` is the
- * same colour in every repository that has one, with no central registry and
- * no chance of two agents in one project colliding by accident.
- *
- * Saturation and lightness are fixed rather than hashed. That is what keeps
- * the result usable: hashing them too would eventually produce near-grey,
- * near-black or near-white agents that are invisible against one theme or the
- * other. Only the hue varies.
- */
-
-/** opencode's theme keywords. Treated as unset so a name-derived hex wins. */
-export const THEME_COLORS = new Set([
-  'primary',
-  'secondary',
-  'accent',
-  'success',
-  'warning',
-  'error',
-  'info',
-])
-
-/** Reserved: the two primaries, which never take a derived colour. */
-export const RESERVED_COLORS = { build: 'primary', plan: 'warning' }
-
-const SATURATION = 68
-const LIGHTNESS = 52
-
-/**
- * FNV-1a, 32 bit. Chosen because it is short enough to duplicate verbatim in
- * the shipped plugin and produces the same hue everywhere: the same name must
- * resolve to the same colour on every machine and in every project.
- */
-function hash(value) {
-  let h = 0x811c9dc5
-  for (let i = 0; i < value.length; i++) {
-    h ^= value.charCodeAt(i)
-    h = Math.imul(h, 0x01000193) >>> 0
-  }
-  return h >>> 0
-}
-
-function hslToHex(h, s, l) {
-  const sat = s / 100
-  const light = l / 100
-  const c = (1 - Math.abs(2 * light - 1)) * sat
-  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
-  const m = light - c / 2
-
-  const [r, g, b] =
-    h < 60 ? [c, x, 0] :
-    h < 120 ? [x, c, 0] :
-    h < 180 ? [0, c, x] :
-    h < 240 ? [0, x, c] :
-    h < 300 ? [x, 0, c] :
-    [c, 0, x]
-
-  const toHex = v => Math.round((v + m) * 255).toString(16).padStart(2, '0')
-  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase()
-}
-
-/** The colour for an agent, honouring the two reserved primaries. */
-export function agentColor(name) {
-  if (name in RESERVED_COLORS) return RESERVED_COLORS[name]
-  return hslToHex(hash(name) % 360, SATURATION, LIGHTNESS)
-}
-
-/**
- * Render a colour for YAML frontmatter.
- *
- * A hex has to be quoted. `#` opens a comment in YAML, so `color: #D83155`
- * parses as null and opencode rejects the agent outright with "Invalid input
- * color". Theme keywords need no quoting and are left bare.
- */
-export function yamlColor(value) {
-  return value.startsWith('#') ? `"${value}"` : value
-}
-
-/** The value of a frontmatter colour, with any quoting removed. */
-export function unquoteColor(raw) {
-  return (raw ?? '').trim().replace(/^["']/, '').replace(/["']$/, '')
-}
-
-/**
- * The frontmatter colour line an agent should have, or null when the current
- * one is already correct. Covers both jobs: choosing the colour, and quoting it
- * so the file actually parses.
- */
-export function colorLineFor(name, rawCurrent) {
-  const current = unquoteColor(rawCurrent)
-  const target = shouldDeriveColor(current) ? agentColor(name) : current
-  const rendered = yamlColor(target)
-  return (rawCurrent ?? '').trim() === rendered ? null : `color: ${rendered}`
-}
-
-/**
- * Whether a frontmatter colour should be replaced by the derived one.
- *
- * A theme keyword is replaced: those came from the old template, which asked
- * whoever ran /make-engineer to pick one and avoid collisions by hand. An
- * explicit hex is left alone, because someone chose it deliberately.
- */
-export function shouldDeriveColor(current) {
-  if (!current) return true
-  return THEME_COLORS.has(current.trim().toLowerCase())
-}
+/**
+ * Deterministic colour for an agent, derived from its name.
+ *
+ * opencode accepts either a hex value or one of its theme keywords. Two of
+ * those keywords are reserved for the primaries so they stay recognisable
+ * across every project: build is `primary`, plan is `warning`. Every other
+ * agent gets a hex derived from its name, so a `butterfly-engineer` is the
+ * same colour in every repository that has one, with no central registry and
+ * no chance of two agents in one project colliding by accident.
+ *
+ * Saturation and lightness are fixed rather than hashed. That is what keeps
+ * the result usable: hashing them too would eventually produce near-grey,
+ * near-black or near-white agents that are invisible against one theme or the
+ * other. Only the hue varies.
+ */
+
+/** opencode's theme keywords. Treated as unset so a name-derived hex wins. */
+export const THEME_COLORS = new Set([
+  'primary',
+  'secondary',
+  'accent',
+  'success',
+  'warning',
+  'error',
+  'info',
+])
+
+/** Reserved: the two primaries, which never take a derived colour. */
+export const RESERVED_COLORS = { build: 'primary', plan: 'warning' }
+
+const SATURATION = 68
+const LIGHTNESS = 52
+
+/**
+ * FNV-1a, 32 bit. Chosen because it is short enough to duplicate verbatim in
+ * the shipped plugin and produces the same hue everywhere: the same name must
+ * resolve to the same colour on every machine and in every project.
+ */
+function hash(value) {
+  let h = 0x811c9dc5
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return h >>> 0
+}
+
+function hslToHex(h, s, l) {
+  const sat = s / 100
+  const light = l / 100
+  const c = (1 - Math.abs(2 * light - 1)) * sat
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = light - c / 2
+
+  const [r, g, b] =
+    h < 60 ? [c, x, 0] :
+    h < 120 ? [x, c, 0] :
+    h < 180 ? [0, c, x] :
+    h < 240 ? [0, x, c] :
+    h < 300 ? [x, 0, c] :
+    [c, 0, x]
+
+  const toHex = v => Math.round((v + m) * 255).toString(16).padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase()
+}
+
+/** The colour for an agent, honouring the two reserved primaries. */
+export function agentColor(name) {
+  if (name in RESERVED_COLORS) return RESERVED_COLORS[name]
+  return hslToHex(hash(name) % 360, SATURATION, LIGHTNESS)
+}
+
+/**
+ * Render a colour for YAML frontmatter.
+ *
+ * A hex has to be quoted. `#` opens a comment in YAML, so `color: #D83155`
+ * parses as null and opencode rejects the agent outright with "Invalid input
+ * color". Theme keywords need no quoting and are left bare.
+ */
+export function yamlColor(value) {
+  return value.startsWith('#') ? `"${value}"` : value
+}
+
+/** The value of a frontmatter colour, with any quoting removed. */
+export function unquoteColor(raw) {
+  return (raw ?? '').trim().replace(/^["']/, '').replace(/["']$/, '')
+}
+
+/**
+ * The frontmatter colour line an agent should have, or null when the current
+ * one is already correct. Covers both jobs: choosing the colour, and quoting it
+ * so the file actually parses.
+ */
+export function colorLineFor(name, rawCurrent) {
+  const current = unquoteColor(rawCurrent)
+  const target = shouldDeriveColor(current) ? agentColor(name) : current
+  const rendered = yamlColor(target)
+  return (rawCurrent ?? '').trim() === rendered ? null : `color: ${rendered}`
+}
+
+/**
+ * Whether a frontmatter colour should be replaced by the derived one.
+ *
+ * A theme keyword is replaced: those came from the old template, which asked
+ * whoever ran /make-engineer to pick one and avoid collisions by hand. An
+ * explicit hex is left alone, because someone chose it deliberately.
+ */
+export function shouldDeriveColor(current) {
+  if (!current) return true
+  return THEME_COLORS.has(current.trim().toLowerCase())
+}

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 = [];
+}