@yeison.restrepo.r/code-conductor 1.53.0 → 1.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -82,7 +82,7 @@ code-conductor assumes these are already in place; the installer does not set th
82
82
  |---|---|---|
83
83
  | Node.js `>= 20` | Running the `code-conductor` CLI itself | Any current Node LTS |
84
84
  | Claude Code | The environment every command, skill and hook here runs inside | See [Anthropic's Claude Code docs](https://code.claude.com/docs) |
85
- | **superpowers plugin** | `/cc-spec` (`brainstorming`), `/cc-plan` (`writing-plans`), and `/cc-debug`, `/cc-refactor`, `/cc-review`, `/cc-test` (all four via `subagent-driven-development`) | Install from Claude Code's `/plugin` marketplace, then run `/reload-plugins`, **before** using these commands; without it, their `Skill(...)` calls fail |
85
+ | **superpowers plugin** | `/cc-spec` (`brainstorming`), `/cc-plan` (`writing-plans`), and `/cc-debug`, `/cc-refactor`, `/cc-review`, `/cc-test` (all four via `subagent-driven-development`) | The installer offers it: an interactive run asks first (default No), and a non-interactive run installs it only with `--with-plugins`. If it cannot install it, it prints the manual fallback and still succeeds: run `/plugin install superpowers@claude-plugins-official` inside Claude Code, then `/reload-plugins`, **before** using these commands; without it, their `Skill(...)` calls fail |
86
86
  | GitHub CLI (`gh`), authenticated | Only `/cc-orchestrate --ticket` and `ticket.mjs writeback`. code-conductor holds no credential; `gh` owns authentication | Install GitHub CLI, then run `gh auth login` |
87
87
  | ui-ux-pro-max skill | Nothing: retired guidance | No shipped code downloads, installs, or activates it. Its replacement is filed as `[FEAT-037]` |
88
88
 
@@ -386,9 +386,10 @@ By default, only the global core files are installed. Flags extend that:
386
386
  | Flag | Description |
387
387
  |---|---|
388
388
  | `--project` / `-Project` | Also install the project template into the current directory |
389
- | `--no-deps` / `-NoDeps` | Accepted for compatibility with the retired shell installers; a no-op, since the npm CLI installs no dependencies and copies agent files only |
389
+ | `--no-deps` / `-NoDeps` | Accepted for compatibility with the retired shell installers; a no-op that copies agent files only and does not affect the superpowers offer (see `--with-plugins`) |
390
390
  | `--verbosity MIN\|INFO\|VERBOSE` / `-Verbosity LEVEL` | Default response verbosity (default `MIN`). `MIN` = one sentence per response, `INFO` = bullet list, `VERBOSE` = full explanation. Re-run the installer to change it. PowerShell's `-Verbosity:INFO` form is not supported; it warns and the level stays `MIN`. |
391
391
  | `--opencode` | With `--project`, also install the OpenCode guard plugin at `.opencode/plugin/conductor-guard.js` (see [OpenCode](#opencode)). Without `--project` it warns and writes nothing for OpenCode |
392
+ | `--with-plugins` | Install the superpowers plugin without asking, through `claude plugin install superpowers@claude-plugins-official` (60 s timeout). A non-interactive run installs it only with this flag; an interactive run asks instead. If the install cannot run, the installer prints `/plugin install superpowers@claude-plugins-official` and still exits 0 |
392
393
 
393
394
  **Updating:** re-run the same install command. User-configured files are never overwritten; agent-managed files are always updated.
394
395
 
@@ -495,7 +496,6 @@ The backup and temp rules keep the installer's own backups and crash-stranded te
495
496
  - Installing or updating copies `.claude/agents/{spec,plan,code,audit,security,qa,define-review}.md` over the host project's files of the same names, as it does every shipped `.claude/` asset.
496
497
  - A gate certifies protocol position and the claim its role states, never the truth of the work beyond that claim.
497
498
  - **The review loop (`1.39.0`) is process discipline.** The spec or plan envelope stays installed after its hand-back, so the role can revise. Outside a round, its writes are bounded by its tool mask, Guard 5's scope, the hash-bound `approve` (`[FEAT-056]`), and your review. Gating Guard 5 on an open round is a follow-up candidate.
498
- - **`[BUG-058]`, open:** the test suite does not pass on a Windows checkout (CRLF checkout of `.mjs` files, `--import` given a bare path, symlink and `chmod` fixtures, `spawnSync('npm')` without a shell), and CI has no Windows leg to show it. Until it is fixed, develop against the suite on Linux/macOS or WSL; the shipped product itself is unaffected.
499
499
  - **`[BUG-089]`, open:** a `--known-failure` entry is matched as a plain substring of a failing test's runner line, so a very short or generic entry can make a red suite read as green, and a newly added failing test whose title contains a declared entry counts as known. Until it is fixed, declare only long, specific entries (for example including the test-file path), and check the matches the start line and the final report list against the failures you meant to declare.
500
500
  - **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned) is still live.
501
501
  - **A re-run against an untouched `project.md` prints a recovery hint it cannot prove is needed.** If you install, never write anything into `.claude/memory/project.md`, and install again, you get a line suggesting the file may have been overwritten by a pre-`1.30.0` re-run. It was not; it equals the stub because it was seeded and never edited. The check compares content and **cannot distinguish "seeded and untouched" from "clobbered"**, which is why the wording is hedged to "may have been" rather than "was". This residual is named and accepted in [`BUG-039`'s spec at `:129`](docs/superpowers/specs/2026-09-27-bug039-installer-host-owned-state-design.md), where the alternative (restoring from the host's own git history) was rejected as writing host files out of the host's history with new failure modes. A **fresh** install is silent, which the Quickstart shows.
@@ -7,8 +7,9 @@ import { assertAssets, assertMergeTargets, assertNotSelfInstall, deployGlobal, d
7
7
  import { verbosityHookCommand, mergeVerbosityHook } from '../lib/installer/settings.mjs';
8
8
  import { healGraphifyHook } from '../lib/installer/heal.mjs';
9
9
  import { writeVerbosity, writeVersionFile } from '../lib/installer/config.mjs';
10
+ import { offerSuperpowers, NOTICES } from '../lib/installer/plugins.mjs';
10
11
 
11
- const USAGE = `Usage: code-conductor [--project|-Project] [--no-deps|-NoDeps] [--verbosity|-Verbosity MIN|INFO|VERBOSE] [--opencode] [--version] [--help]`;
12
+ const USAGE = `Usage: code-conductor [--project|-Project] [--no-deps|-NoDeps] [--verbosity|-Verbosity MIN|INFO|VERBOSE] [--opencode] [--with-plugins] [--version] [--help]`;
12
13
 
13
14
  // -Verbosity is the spelling the retired install.ps1 documented. Both spellings share
14
15
  // every form (space-separated, inline `=`, missing value) and last-wins across them.
@@ -23,18 +24,21 @@ const isVerbosityFlag = (a) => VERBOSITY_FLAGS.some((f) => a === f || a.startsWi
23
24
  // is idempotent. No "conflicting flags" error is raised — last-wins is the least
24
25
  // surprising CLI convention and keeps the parser branchless.
25
26
  function parseArgs(argv) {
26
- const opts = { project: false, opencode: false, noDeps: false, verbosity: undefined, verbosityGiven: false, version: false, help: false, unknown: [] };
27
+ const opts = { project: false, opencode: false, noDeps: false, withPlugins: false, verbosity: undefined, verbosityGiven: false, version: false, help: false, unknown: [] };
27
28
  for (let i = 0; i < argv.length; i++) {
28
29
  const a = argv[i];
29
30
  // -Project is the spelling the retired install.ps1 documented; matched exact-case
30
31
  // like every other flag here.
31
32
  if (a === '--project' || a === '-Project') opts.project = true;
32
- // Accepted no-op: the npm CLI installs no dependencies since FEAT-023 removed the
33
- // shell installers, so there is nothing to skip. Recognized so callers carried over
34
- // from install.sh get no misleading "unrecognized" warning.
33
+ // Accepted no-op since FEAT-023 removed the shell installers: recognized so callers
34
+ // carried over from install.sh get no misleading "unrecognized" warning. It does not
35
+ // affect the superpowers offer, which only --with-plugins or the prompt controls.
35
36
  else if (a === '--no-deps' || a === '-NoDeps') opts.noDeps = true;
36
37
  // FEAT-048: also install the OpenCode guard plugin; meaningful only with --project.
37
38
  else if (a === '--opencode') opts.opencode = true;
39
+ // FEAT-039: consent to install the superpowers plugin without asking; the only way a
40
+ // non-interactive run installs it. Matched exact-case like every other flag.
41
+ else if (a === '--with-plugins') opts.withPlugins = true;
38
42
  else if (isVerbosityFlag(a)) {
39
43
  opts.verbosityGiven = true;
40
44
  if (a.includes('=')) {
@@ -66,8 +70,20 @@ function pkgVersion(assetRoot) {
66
70
  return JSON.parse(readFileSync(join(assetRoot, 'package.json'), 'utf8')).version;
67
71
  }
68
72
 
69
- // log(stream, msg) is injected so tests capture output without spawning a process.
70
- export function run(argv, env = process.env, { cwd = process.cwd(), log, nodeVersion = process.versions.node } = {}) {
73
+ // FEAT-039: the last setup step, fail-open. Its own try keeps it out of run()'s exit
74
+ // classes: nothing here can turn a finished deploy into an exit 1 or 2.
75
+ function offerPlugins(emit, options) {
76
+ try {
77
+ const result = offerSuperpowers(options);
78
+ if (NOTICES[result.status]) emit('stdout', `code-conductor: ${NOTICES[result.status]}`);
79
+ for (const line of result.lines) emit('stderr', `code-conductor: ${line}`);
80
+ } catch { /* fail-open: a reporting error never changes the exit code */ }
81
+ }
82
+
83
+ // log(stream, msg) is injected so tests capture output without spawning a process. The
84
+ // plugin options (FEAT-039) let tests replace the TTY check, the prompt, the spawn, the
85
+ // timeout and the child's env, so no test can prompt or reach a real claude.
86
+ export function run(argv, env = process.env, { cwd = process.cwd(), log, nodeVersion = process.versions.node, isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY), ask, spawn, pluginTimeoutMs, pluginEnv = process.env } = {}) {
71
87
  const emit = log || ((stream, msg) => process[stream].write(`${msg}\n`));
72
88
 
73
89
  // Hard runtime floor: refuse to run on Node < 20 with a clear message rather than
@@ -121,6 +137,7 @@ export function run(argv, env = process.env, { cwd = process.cwd(), log, nodeVer
121
137
  for (const line of heal.lines) emit('stderr', `code-conductor: ${line}`);
122
138
  writeVersionFile(home, pkgVersion(assetRoot));
123
139
  if (opts.project) deployProject(assetRoot, cwd, { warn: (m) => emit('stderr', m), report: (m) => emit('stdout', m), home, opencode: opts.opencode });
140
+ offerPlugins(emit, { home, withPlugins: opts.withPlugins, isInteractive, ask, spawn, timeoutMs: pluginTimeoutMs, env: pluginEnv });
124
141
  return 0;
125
142
  } catch (err) {
126
143
  // Pre-flight failures (nothing written yet) → exit 1.
@@ -0,0 +1,117 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { closeSync, mkdtempSync, openSync, readFileSync, readSync, rmSync } from 'node:fs';
3
+ import { tmpdir } from 'node:os';
4
+ import { join } from 'node:path';
5
+
6
+ // FEAT-039: the one place the plugin spec lives. Every command string, prompt and
7
+ // registry key below is built from it, so a marketplace rename is a one-line change
8
+ // that tests/installer/plugins.test.js pins.
9
+ export const SUPERPOWERS_PLUGIN = 'superpowers@claude-plugins-official';
10
+ export const MANUAL_COMMAND = `/plugin install ${SUPERPOWERS_PLUGIN}`;
11
+ export const DEFAULT_TIMEOUT_MS = 60000;
12
+ const MARKETPLACE = SUPERPOWERS_PLUGIN.slice(SUPERPOWERS_PLUGIN.indexOf('@') + 1);
13
+ export const CONSENT_PROMPT = `Install the superpowers plugin (third-party code, from the ${MARKETPLACE} marketplace) with 'claude plugin install ${SUPERPOWERS_PLUGIN}'? [y/N] `;
14
+ export const NOTICES = {
15
+ installed: 'installed the superpowers plugin; run /reload-plugins in any open Claude Code session',
16
+ already: 'superpowers plugin already installed',
17
+ };
18
+
19
+ export const fallbackLine = (reason) => `superpowers plugin not installed (${reason}); install it inside Claude Code: ${MANUAL_COMMAND}`;
20
+ export const formatTimeout = (ms) => (ms % 1000 === 0 ? `${ms / 1000}s` : `${ms}ms`);
21
+
22
+ // Claude Code's registry, not ours: a miss only costs the offer, never a failure.
23
+ export function isRegistered(home) {
24
+ try {
25
+ const registry = JSON.parse(readFileSync(join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8'));
26
+ const plugins = registry?.plugins;
27
+ return typeof plugins === 'object' && plugins !== null && Object.hasOwn(plugins, SUPERPOWERS_PLUGIN);
28
+ } catch { return false; }
29
+ }
30
+
31
+ // Synchronous so run() keeps its sync contract; one byte at a time so nothing past the
32
+ // answer is consumed. EOF ends the line, so a closed stdin reads as a declined answer.
33
+ export function readLine(fd = 0, read = readSync) {
34
+ const byte = Buffer.alloc(1);
35
+ let line = '';
36
+ while (line.length < 256 && read(fd, byte, 0, 1, null) === 1) {
37
+ const ch = byte.toString('latin1');
38
+ if (ch === '\n') break;
39
+ line += ch;
40
+ }
41
+ return line;
42
+ }
43
+
44
+ const askOnTerminal = (question) => { process.stdout.write(question); return readLine(); };
45
+
46
+ // FEAT-037 consent rule: third-party code is offered, never silently run.
47
+ function refusalReason({ withPlugins, isInteractive, ask }) {
48
+ if (withPlugins) return null;
49
+ if (!isInteractive) return 'non-interactive run; pass --with-plugins to install it';
50
+ let answer;
51
+ try { answer = ask(CONSENT_PROMPT); } catch { return 'declined'; }
52
+ return /^(y|yes)$/i.test(String(answer ?? '').trim()) ? null : 'declined';
53
+ }
54
+
55
+ function removeQuietly(rm, dir) {
56
+ // Best-effort: on win32 an orphaned grandchild can still hold the files (EBUSY), and the
57
+ // outcome is already fixed, so a cleanup error must never become the reported reason.
58
+ try { rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* leftover tmp dir is harmless */ }
59
+ }
60
+
61
+ // Files, not pipes: a grandchild that inherited a pipe (cmd.exe's claude, or a git clone)
62
+ // would hold spawnSync past the timeout; with file descriptors there is nothing to wait on.
63
+ function spawnInstall({ spawn, timeoutMs, env, platform, rm }) {
64
+ const dir = mkdtempSync(join(tmpdir(), 'cc-plugin-'));
65
+ const outPath = join(dir, 'out');
66
+ const errPath = join(dir, 'err');
67
+ const fds = [];
68
+ try {
69
+ fds.push(openSync(outPath, 'w'), openSync(errPath, 'w'));
70
+ // cwd is our empty temp dir: cmd.exe (and a PATH holding '.') resolves a bare `claude`
71
+ // from the current directory first, so a claude.cmd committed to the project must not run.
72
+ const options = { stdio: ['ignore', fds[0], fds[1]], timeout: timeoutMs, windowsHide: true, env, cwd: dir };
73
+ // win32: one string and no args array, so claude.cmd resolves and DEP0190 does not fire.
74
+ // The string holds only literals and the constant; no user input reaches the shell.
75
+ const result = platform === 'win32'
76
+ ? spawn(`claude plugin install ${SUPERPOWERS_PLUGIN}`, { ...options, shell: true })
77
+ : spawn('claude', ['plugin', 'install', SUPERPOWERS_PLUGIN], options);
78
+ return { ...result, stdoutText: readFileSync(outPath, 'utf8'), stderrText: readFileSync(errPath, 'utf8') };
79
+ } finally {
80
+ for (const fd of fds) closeSync(fd);
81
+ removeQuietly(rm, dir);
82
+ }
83
+ }
84
+
85
+ const failed = (reason, diagnostic = '') => ({
86
+ status: 'failed',
87
+ lines: diagnostic ? [fallbackLine(reason), `claude plugin install said: ${diagnostic}`] : [fallbackLine(reason)],
88
+ });
89
+
90
+ function notFound(result, platform) {
91
+ if (result.error?.code === 'ENOENT') return true;
92
+ return platform === 'win32' && (result.status === 9009 || /is not recognized/i.test(result.stderrText));
93
+ }
94
+
95
+ // The CLI's error text is not ours and changes between releases, so every other
96
+ // non-zero exit is one generic reason plus the first stderr line as context.
97
+ export function classifyInstall(result, { timeoutMs, platform }) {
98
+ if (notFound(result, platform)) return failed('claude CLI not found on PATH');
99
+ if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') return failed(`timed out after ${formatTimeout(timeoutMs)}`);
100
+ if (result.error) return failed(`unexpected error: ${result.error.message}`);
101
+ if (result.status === 0) return { status: 'installed', lines: [] };
102
+ if (/already installed/i.test(`${result.stdoutText}\n${result.stderrText}`)) return { status: 'already', lines: [] };
103
+ const firstLine = result.stderrText.split(/\r?\n/, 1)[0].trim().slice(0, 200);
104
+ return failed(`claude plugin install failed (exit ${result.status})`, firstLine);
105
+ }
106
+
107
+ // Never throws: like the installer heal, every outcome is a status plus lines for bin to emit.
108
+ export function offerSuperpowers({ home, withPlugins = false, isInteractive = false, ask = askOnTerminal, spawn = spawnSync, timeoutMs = DEFAULT_TIMEOUT_MS, env = process.env, platform = process.platform, rm = rmSync } = {}) {
109
+ try {
110
+ if (isRegistered(home)) return { status: 'already', lines: [] };
111
+ const reason = refusalReason({ withPlugins, isInteractive, ask });
112
+ if (reason) return { status: 'skipped', lines: [fallbackLine(reason)] };
113
+ return classifyInstall(spawnInstall({ spawn, timeoutMs, env, platform, rm }), { timeoutMs, platform });
114
+ } catch (e) {
115
+ return { status: 'failed', lines: [fallbackLine(`unexpected error: ${e.message}`)] };
116
+ }
117
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yeison.restrepo.r/code-conductor",
3
- "version": "1.53.0",
3
+ "version": "1.54.0",
4
4
  "description": "A governance layer for Claude Code sessions: hooks that check an agent's commands before they run, a spec-first workflow, and project memory the next session reads.",
5
5
  "keywords": [
6
6
  "agentic-development",