ctxora 6.2.2 → 6.3.0

package/src/harness_context/skills/ecc/terminal-opener/scripts/open-terminal.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const path = require('path');
+const childProcess = require('child_process');
+
+const DEFAULT_TERMINAL = 'wezterm';
+const SPAWN_KILL_SIGNAL = 'SIGTERM';
+const SYNC_TIMEOUT_MS = 10_000;
+const SUPPORTED_TERMINALS = new Set([DEFAULT_TERMINAL]);
+
+function usage() {
+  return `Open an executable and its argument array in a visible terminal.
+
+Usage:
+  node skills/terminal-opener/scripts/open-terminal.js [options] -- <executable> [args...]
+  node skills/terminal-opener/scripts/open-terminal.js --detect [--terminal <name>] [--json]
+
+Options:
+  --terminal <name>  Terminal adapter (default: ECC_TERMINAL or wezterm).
+  --cwd <path>       Initial host directory (default: current directory).
+  --recover          Start a standalone terminal with stock configuration.
+  --standalone       Alias for --recover.
+  --detect           Check whether the selected terminal can be launched.
+  --launch           Explicitly open the terminal (the default only prints a plan).
+  --dry-run          Explicitly print the launch plan without opening a terminal.
+  --json             Emit the plan, capability, or launch result as JSON.
+  --help, -h         Show this help.
+
+Always pass the executable and arguments as separate entries after --.
+Shell command strings are not accepted.
+`;
+}
+
+function isAbsolutePath(value) {
+  return path.isAbsolute(value) || path.win32.isAbsolute(value);
+}
+
+function validateTerminalName(value) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value)) {
+    throw new Error('Invalid terminal name; use a simple adapter name such as wezterm.');
+  }
+}
+
+function validateCwd(value) {
+  if (value.includes('\0')) throw new Error('--cwd must not contain a NUL byte.');
+  if (!isAbsolutePath(value)) throw new Error('--cwd must be an absolute path.');
+}
+
+function validateExecutable(value) {
+  if (!value || /[\0\r\n]/.test(value)) {
+    throw new Error('Executable must be a non-empty argv entry without control bytes.');
+  }
+
+  const whitespaceIndex = value.search(/\s/);
+  const separatorIndexes = [value.indexOf('/'), value.indexOf('\\')].filter(index => index >= 0);
+  const firstSeparatorIndex = separatorIndexes.length > 0 ? Math.min(...separatorIndexes) : -1;
+  const resemblesExecutablePath = isAbsolutePath(value)
+    || (firstSeparatorIndex >= 0 && (whitespaceIndex < 0 || firstSeparatorIndex < whitespaceIndex));
+
+  if (whitespaceIndex >= 0 && !resemblesExecutablePath) {
+    throw new Error(
+      'Executable must be one argv entry, not an interpolated shell command string.'
+    );
+  }
+  if (!resemblesExecutablePath && /[;&|<>`$]/.test(value)) {
+    throw new Error(
+      'Executable must be one argv entry, not an interpolated shell command string.'
+    );
+  }
+}
+
+function validateArgv(argv) {
+  for (const argument of argv) {
+    if (argument.includes('\0')) throw new Error('Arguments must not contain NUL bytes.');
+  }
+}
+
+function readValue(argv, index, option) {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`Missing value for ${option}.`);
+  }
+  return value;
+}
+
+function parseArgs(argv, context = {}) {
+  const env = context.env || process.env;
+  const initialTerminal = env.ECC_TERMINAL || DEFAULT_TERMINAL;
+  const initialCwd = context.cwd || process.cwd();
+  const options = {
+    argv: [],
+    cwd: initialCwd,
+    detect: false,
+    dryRun: true,
+    executable: undefined,
+    help: false,
+    json: false,
+    mode: 'normal',
+    terminal: initialTerminal,
+  };
+  let dryRunRequested = false;
+  let launchRequested = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') {
+      options.executable = argv[index + 1];
+      options.argv = argv.slice(index + 2);
+      break;
+    }
+    if (argument === '--terminal' || argument === '--cwd') {
+      const value = readValue(argv, index, argument);
+      options[argument.slice(2)] = value;
+      index += 1;
+    } else if (argument === '--recover' || argument === '--standalone') {
+      options.mode = 'recover';
+    } else if (argument === '--detect') {
+      options.detect = true;
+    } else if (argument === '--launch') {
+      launchRequested = true;
+      options.dryRun = false;
+    } else if (argument === '--dry-run') {
+      dryRunRequested = true;
+      options.dryRun = true;
+    } else if (argument === '--json') {
+      options.json = true;
+    } else if (argument === '--help' || argument === '-h') {
+      options.help = true;
+    } else {
+      throw new Error(`Unknown option "${argument}"; put the executable after --.`);
+    }
+  }
+
+  if (launchRequested && dryRunRequested) {
+    throw new Error('--launch and --dry-run are mutually exclusive.');
+  }
+
+  validateTerminalName(options.terminal);
+  validateCwd(options.cwd);
+  if (!options.help && !options.detect && !options.executable) {
+    throw new Error('An executable is required after --.');
+  }
+  if (options.executable) validateExecutable(options.executable);
+  validateArgv(options.argv);
+  return options;
+}
+
+function unsupportedPlan(options) {
+  return {
+    ok: false,
+    reason: 'unsupported-terminal',
+    action: `Terminal "${options.terminal}" is not supported. Install WezTerm, then rerun with --terminal wezterm.`,
+    terminal: options.terminal,
+    executable: options.executable,
+    argv: [...options.argv],
+    cwd: options.cwd,
+    dryRun: options.dryRun,
+    launchMode: options.mode === 'recover' ? 'recover' : 'mux',
+    command: null,
+    args: null,
+    fallback: null,
+    probe: null,
+  };
+}
+
+function buildLaunchPlan(options) {
+  if (!SUPPORTED_TERMINALS.has(options.terminal)) return unsupportedPlan(options);
+
+  const commandArgs = options.executable ? [options.executable, ...options.argv] : [];
+  const recover = options.mode === 'recover';
+  return {
+    ok: true,
+    reason: null,
+    action: null,
+    terminal: options.terminal,
+    executable: options.executable,
+    argv: [...options.argv],
+    cwd: options.cwd,
+    dryRun: options.dryRun,
+    launchMode: recover ? 'recover' : 'mux',
+    command: DEFAULT_TERMINAL,
+    args: recover
+      ? ['--skip-config', 'start', '--always-new-process', '--cwd', options.cwd, '--', ...commandArgs]
+      : ['cli', 'spawn', '--new-window', '--cwd', options.cwd, '--', ...commandArgs],
+    fallback: recover
+      ? null
+      : {
+          command: DEFAULT_TERMINAL,
+          args: ['start', '--cwd', options.cwd, '--', ...commandArgs],
+        },
+    probe: { command: DEFAULT_TERMINAL, args: ['--version'] },
+  };
+}
+
+function unavailableCapability(plan, reason, detail) {
+  return {
+    terminal: plan.terminal,
+    supported: true,
+    available: false,
+    reason,
+    detail,
+    action: 'Install WezTerm and ensure wezterm is on PATH, then rerun with --detect.',
+  };
+}
+
+function detectTerminalCapability(plan, spawnSyncImpl = childProcess.spawnSync) {
+  if (!plan.ok) {
+    return {
+      terminal: plan.terminal,
+      supported: false,
+      available: false,
+      reason: plan.reason,
+      detail: null,
+      action: plan.action,
+    };
+  }
+
+  let result;
+  try {
+    result = spawnSyncImpl(plan.probe.command, plan.probe.args, {
+      encoding: 'utf8',
+      killSignal: SPAWN_KILL_SIGNAL,
+      shell: false,
+      timeout: SYNC_TIMEOUT_MS,
+    });
+  } catch (error) {
+    return unavailableCapability(plan, 'probe-failed', error.message);
+  }
+  if (result.error) {
+    const reason = result.error.code === 'ETIMEDOUT' ? 'probe-failed' : 'not-installed';
+    return unavailableCapability(plan, reason, result.error.message);
+  }
+  if (result.status !== 0) {
+    return unavailableCapability(
+      plan,
+      'probe-failed',
+      `Terminal version probe exited with status ${result.status}.`
+    );
+  }
+  return {
+    terminal: plan.terminal,
+    supported: true,
+    available: true,
+    reason: null,
+    detail: null,
+    action: null,
+    version: String(result.stdout || '').trim(),
+  };
+}
+
+function reportDetachedError(error) {
+  process.stderr.write(`Error: ${error.message}\n`);
+  process.exitCode = 1;
+}
+
+function launchDetached(command, args, cwd, spawnImpl, onDetachedError) {
+  let child;
+  try {
+    child = spawnImpl(command, args, {
+      cwd,
+      detached: true,
+      shell: false,
+      stdio: 'ignore',
+    });
+  } catch (error) {
+    throw new Error(`Unable to start ${command}: ${error.message}`, { cause: error });
+  }
+  if (!child || typeof child.unref !== 'function') {
+    throw new Error('Terminal process did not start correctly.');
+  }
+  if (typeof child.once === 'function') {
+    child.once('error', error => {
+      onDetachedError(
+        new Error(`Unable to start ${command}: ${error.message}`, { cause: error })
+      );
+    });
+  }
+  child.unref();
+}
+
+function launch(plan, dependencies = {}) {
+  const spawnSyncImpl = dependencies.spawnSync || childProcess.spawnSync;
+  const spawnImpl = dependencies.spawn || childProcess.spawn;
+  const onDetachedError = dependencies.onDetachedError || reportDetachedError;
+  const capability = detectTerminalCapability(plan, spawnSyncImpl);
+  if (!capability.available) {
+    throw new Error(`${capability.reason}: ${capability.action}`);
+  }
+
+  if (plan.launchMode === 'recover') {
+    launchDetached(plan.command, plan.args, plan.cwd, spawnImpl, onDetachedError);
+    return { strategy: 'detached-recover', capability };
+  }
+
+  const muxResult = spawnSyncImpl(plan.command, plan.args, {
+    cwd: plan.cwd,
+    encoding: 'utf8',
+    killSignal: SPAWN_KILL_SIGNAL,
+    shell: false,
+    timeout: SYNC_TIMEOUT_MS,
+  });
+  if (!muxResult.error && muxResult.status === 0) {
+    return { strategy: 'mux', capability };
+  }
+
+  const muxFailure = muxResult.error
+    ? muxResult.error.message
+    : `${plan.command} cli spawn exited with status ${muxResult.status}: ${String(
+        muxResult.stderr || ''
+      ).trim()}`;
+
+  launchDetached(
+    plan.fallback.command,
+    plan.fallback.args,
+    plan.cwd,
+    spawnImpl,
+    onDetachedError
+  );
+  return { strategy: 'detached-fallback', capability, muxFailure };
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function formatLaunchResult(plan, result, json) {
+  if (json) {
+    return `${JSON.stringify({ ...plan, ...result }, null, 2)}\n`;
+  }
+
+  const summary =
+    `Open ${plan.executable} in ${plan.terminal} using ${plan.launchMode} mode.\n`;
+  if (result.strategy !== 'detached-fallback') return summary;
+  return `${summary}Mux launch failed: ${result.muxFailure}\n`;
+}
+
+function printPlan(plan, json) {
+  if (json) return printJson(plan);
+  if (!plan.ok) {
+    process.stdout.write(`${plan.action}\n`);
+    return;
+  }
+  process.stdout.write(
+    `Open ${plan.executable} in ${plan.terminal} using ${plan.launchMode} mode.\n`
+  );
+}
+
+function printCapability(capability, json) {
+  if (json) return printJson(capability);
+  if (capability.available) {
+    process.stdout.write(`${capability.terminal} is available (${capability.version}).\n`);
+  } else {
+    process.stdout.write(`${capability.terminal} is unavailable. ${capability.action}\n`);
+  }
+}
+
+function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      process.stdout.write(usage());
+      return;
+    }
+
+    const plan = buildLaunchPlan(options);
+    if (options.detect) {
+      const capability = detectTerminalCapability(plan);
+      printCapability(capability, options.json);
+      if (!capability.available) process.exitCode = 1;
+      return;
+    }
+
+    if (options.dryRun) {
+      printPlan(plan, options.json);
+      return;
+    }
+    const result = launch(plan);
+    process.stdout.write(formatLaunchResult(plan, result, options.json));
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  buildLaunchPlan,
+  detectTerminalCapability,
+  formatLaunchResult,
+  launch,
+  parseArgs,
+  usage,
+};

package/src/harness_context/skills/ecc/terminal-ops/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/terminal-ops/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: terminal-ops
+description: Evidence-first repo execution workflow for ECC. Use when the user wants a command run, a repo checked, a CI failure debugged, or a narrow fix pushed with exact proof of what was executed and verified.
+metadata:
+  origin: ECC
+---
+
+# Terminal Ops
+
+Use this when the user wants real repo execution: run commands, inspect git state, debug CI or builds, make a narrow fix, and report exactly what changed and what was verified.
+
+This skill is intentionally narrower than general coding guidance. It is an operator workflow for evidence-first terminal execution.
+
+## Skill Stack
+
+Pull these ECC-native skills into the workflow when relevant:
+
+- `verification-loop` for exact proving steps after changes
+- `tdd-workflow` when the right fix needs regression coverage
+- `security-review` when secrets, auth, or external inputs are involved
+- `github-ops` when the task depends on CI runs, PR state, or release status
+- `knowledge-ops` when the verified outcome needs to be captured into durable project context
+
+## When to Use
+
+- user says "fix", "debug", "run this", "check the repo", or "push it"
+- the task depends on command output, git state, test results, or a verified local fix
+- the answer must distinguish changed locally, verified locally, committed, and pushed
+
+## Guardrails
+
+- inspect before editing
+- stay read-only if the user asked for audit/review only
+- prefer repo-local scripts and helpers over improvised ad hoc wrappers
+- do not claim fixed until the proving command was rerun
+- do not claim pushed unless the branch actually moved upstream
+
+## Workflow
+
+### 1. Resolve the working surface
+
+Settle:
+
+- exact repo path
+- branch
+- local diff state
+- requested mode:
+  - inspect
+  - fix
+  - verify
+  - push
+
+### 2. Read the failing surface first
+
+Before changing anything:
+
+- inspect the error
+- inspect the file or test
+- inspect git state
+- use any already-supplied logs or context before re-reading blindly
+
+### 3. Keep the fix narrow
+
+Solve one dominant failure at a time:
+
+- use the smallest useful proving command first
+- only escalate to a bigger build/test pass after the local failure is addressed
+- if a command keeps failing with the same signature, stop broad retries and narrow scope
+
+### 4. Report exact execution state
+
+Use exact status words:
+
+- inspected
+- changed locally
+- verified locally
+- committed
+- pushed
+- blocked
+
+## Output Format
+
+```text
+SURFACE
+- repo
+- branch
+- requested mode
+
+EVIDENCE
+- failing command / diff / test
+
+ACTION
+- what changed
+
+STATUS
+- inspected / changed locally / verified locally / committed / pushed / blocked
+```
+
+## Pitfalls
+
+- do not work from stale memory when the live repo state can be read
+- do not widen a narrow fix into repo-wide churn
+- do not use destructive git commands
+- do not ignore unrelated local work
+
+## Verification
+
+- the response names the proving command or test
+- git-related work names the repo path and branch
+- any push claim includes the target branch and exact result

package/src/harness_context/skills/ecc/tinystruct-patterns/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.