@selesai/code 0.9.11 → 0.9.12

package/dist/skills/unlazy/scripts/gate-lint.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// gate-lint.mjs : audit whether a ledger is worth passing.
+// Zero dependencies. Node 16+.
+//
+// The checker and the Stop hook decide whether gates were met. Neither asks
+// whether the gates were worth meeting. A gate reading "the entire feature
+// works perfectly" with `CHECK: echo ok` and `EXPECT: ok` passes the checker,
+// the parent re-verification and the hook, because the oracle is real, runs,
+// and returns what it promised. Authoring is the one step in the enforcement
+// hierarchy that is still pure prose discipline, and this lints it.
+//
+// This never executes a CHECK. It reads the ledger and judges its oracles.
+//
+//   node gate-lint.mjs [options] <ledger.md ...>
+//     --strict   treat warnings as failures
+//     --json     machine-readable findings
+//
+// exit codes: 0 no strict failures, 1 strict findings, 2 usage or parse error.
+//
+// Usable as a gate, so a ledger can require its own quality:
+//   CHECK: node scripts/gate-lint.mjs GATES.md
+//   EXPECT: LINT OK
+
+import { readFileSync } from "node:fs";
+import { parseGates } from "./lib/gates.mjs";
+
+const HELP = `usage: gate-lint.mjs [--strict] [--json] <ledger.md ...>
+
+Audit gate quality, not gate completion. Report lexical signs of fixed-output
+oracles, weak expectations, manual measurements, and titles that name an
+activity instead of an outcome. Never executes a CHECK.
+
+exit codes: 0 no strict failures, 1 strict findings, 2 usage or parse error.`;
+
+const KNOWN_OPTIONS = new Set(["--strict", "--json", "--help", "-h"]);
+
+const args = process.argv.slice(2);
+if (!args.length) {
+  console.error(HELP);
+  process.exit(2);
+}
+// `--` makes every following token a filename, including literal files named
+// `--help` and `-h`. Only scan the option prefix for the help flags.
+const positionalIndex = args.indexOf("--");
+const optionPrefix = positionalIndex === -1 ? args : args.slice(0, positionalIndex);
+if (optionPrefix.includes("--help") || optionPrefix.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+let strict = false;
+let asJson = false;
+let positional = false;
+const files = [];
+for (const arg of args) {
+  if (!positional && arg === "--") { positional = true; continue; }
+  if (!positional && KNOWN_OPTIONS.has(arg)) {
+    if (arg === "--strict") strict = true;
+    else if (arg === "--json") asJson = true;
+    continue;
+  }
+  if (!positional && arg.startsWith("-")) {
+    console.error("gate-lint: unknown option " + arg);
+    console.error("run gate-lint.mjs --help for usage");
+    process.exit(2);
+  }
+  files.push(arg);
+}
+if (!files.length) {
+  console.error("gate-lint: name at least one ledger file");
+  process.exit(2);
+}
+
+// This is deliberately advisory and whole-command only. Shell text beginning
+// with `echo` can still chain a real verifier, and argv containing EXPECT says
+// nothing about what the called program prints or whether it exits zero.
+const FIXED_OUTPUT_COMMAND = /^\s*(?:(?:echo|printf)(?:\s+[^&|;]*)?|true|:|exit\s+0)\s*$/i;
+// Tokens that appear in failure output as readily as in success output.
+const WEAK_EXPECT = new Set([
+  "ok", "okay", "done", "pass", "passed", "success", "successful", "succeeded",
+  "complete", "completed", "finished", "yes", "true", "0", "good", "fine", "working",
+]);
+// Openings that name an activity rather than an outcome a stranger could judge.
+const ACTIVITY_START = /^(work(ing)? on|improve|enhance|handle|support|ensure|make sure|try|attempt|look (at|into)|investigate|consider|review|refactor|clean ?up|polish|update|tidy|address|deal with|add support)\b/i;
+const findings = [];
+const add = (file, level, gate, rule, message) =>
+  findings.push({ file, level, gate: gate || null, rule, message });
+
+let parseFailed = false;
+
+for (const file of files) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    console.error("gate-lint: cannot read " + file + ": " + error.message);
+    process.exit(2);
+  }
+
+  const doc = parseGates(text);
+  if (doc.errors.length) {
+    // A ledger the shared parser rejects cannot be judged on quality.
+    parseFailed = true;
+    for (const error of doc.errors) add(file, "error", null, "parse", error);
+    continue;
+  }
+
+  const live = doc.gates.filter((gate) => !doc.abandoned.has(gate.id));
+  const runnable = live.filter((gate) => gate.check);
+
+  for (const gate of live) {
+    const { id, title, check, expect } = gate;
+
+    if (check && FIXED_OUTPUT_COMMAND.test(check)) {
+      add(file, "warn", id, "tautological-check",
+        'CHECK looks like a fixed-output command: "' + check + '"; use an oracle that observes the named outcome');
+    }
+
+    if (expect && WEAK_EXPECT.has(expect.trim().toLowerCase())) {
+      add(file, "warn", id, "weak-expect",
+        'EXPECT "' + expect + '" also appears in failure output; match a line only success can print');
+    }
+
+    if (gate.expectation && gate.expectation.kind === "regex" && gate.expectation.pathLike) {
+      add(file, "warn", id, "path-read-as-regex",
+        'EXPECT "' + expect + '" looks like a literal path but is read as a regular expression, so its dots are wildcards');
+    }
+
+    if (!check) {
+      add(file, "warn", id, "manual-gate",
+        "no CHECK, so this outcome is judged by hand and its evidence is only as good as the reader");
+      if (/\d/.test(title)) {
+        add(file, "warn", id, "unmeasured-number",
+          'title states a number that nothing measures: "' + title + '"');
+      }
+    }
+
+    if (ACTIVITY_START.test(title)) {
+      add(file, "warn", id, "activity-not-outcome",
+        'names an activity, not an outcome a stranger could judge: "' + title + '"');
+    }
+  }
+
+  if (live.length && runnable.length / live.length < 0.5) {
+    add(file, "warn", null, "mostly-manual",
+      runnable.length + "/" + live.length + " gates are runnable; a mostly manual ledger is prose with checkboxes");
+  }
+}
+
+const errors = findings.filter((f) => f.level === "error");
+const warnings = findings.filter((f) => f.level === "warn");
+const failed = errors.length > 0 || (strict && warnings.length > 0);
+
+if (asJson) {
+  console.log(JSON.stringify({
+    ok: !failed,
+    errors: errors.length,
+    warnings: warnings.length,
+    findings,
+  }, null, 2));
+} else {
+  let lastFile = null;
+  for (const finding of findings) {
+    if (finding.file !== lastFile) {
+      console.log(finding.file);
+      lastFile = finding.file;
+    }
+    const label = finding.level === "error" ? "ERROR" : "WARN ";
+    const who = finding.gate ? finding.gate + ": " : "";
+    console.log("  " + label + " " + who + finding.message + "  [" + finding.rule + "]");
+  }
+  if (!failed) {
+    console.log(warnings.length ? "LINT OK (" + warnings.length + " warning(s))" : "LINT OK");
+  } else {
+    console.log("LINT FINDINGS: " + errors.length + " error(s), " + warnings.length + " warning(s)");
+  }
+}
+
+process.exit(parseFailed ? 2 : failed ? 1 : 0);

package/dist/skills/unlazy/scripts/install-hooks.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// Install or remove unlazy's Claude Code Stop hook. Zero dependencies. Node 16+.
+
+import {
+  closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync,
+  openSync, readFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { validateScopeId, writeAtomic } from "./lib/gates.mjs";
+
+const HELP = `usage: install-hooks.mjs [--scope ID] [--shared | --global] [--uninstall]
+
+  default       .claude/settings.local.json in the current project
+  --shared      .claude/settings.json in the current project
+  --global      ~/.claude/settings.json
+  --scope ID    pin the hook to one validated .unlazy/ID pipeline
+  --uninstall   remove only unlazy handlers, preserving sibling handlers`;
+
+function usage(message) {
+  console.error("install-hooks: " + message);
+  console.error("run install-hooks.mjs --help for usage");
+  process.exit(2);
+}
+
+const args = process.argv.slice(2);
+const known = new Set(["--scope", "--shared", "--global", "--uninstall", "--help", "-h"]);
+let scope = null;
+let shared = false;
+let global = false;
+let uninstall = false;
+for (let index = 0; index < args.length; index++) {
+  const arg = args[index];
+  if (!known.has(arg)) usage("unknown option " + arg);
+  if (arg === "--help" || arg === "-h") { console.log(HELP); process.exit(0); }
+  if (arg === "--scope") {
+    if (scope !== null) usage("duplicate --scope");
+    scope = args[++index];
+    if (!scope) usage("--scope needs a pipeline id");
+    continue;
+  }
+  if (arg === "--shared") shared = true;
+  if (arg === "--global") global = true;
+  if (arg === "--uninstall") uninstall = true;
+}
+if (shared && global) usage("--shared and --global are mutually exclusive");
+if (scope) {
+  const error = validateScopeId(scope);
+  if (error) usage(error);
+}
+
+const script = fileURLToPath(new URL("./stop-hook.mjs", import.meta.url));
+const MANAGED_MARKER = "--unlazy-hook-v2";
+const target = global
+  ? join(homedir(), ".claude", "settings.json")
+  : join(process.cwd(), ".claude", shared ? "settings.json" : "settings.local.json");
+const backup = target + ".unlazy.bak";
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+let raw = "";
+let settings = {};
+if (existsSync(target)) {
+  let fd = null;
+  try {
+    const noFollow = process.platform === "win32" ? 0 : (fsConstants.O_NOFOLLOW || 0);
+    fd = openSync(target, fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK || 0) | noFollow);
+    const opened = fstatSync(fd);
+    const named = lstatSync(target);
+    if (!opened.isFile() || !named.isFile() || named.isSymbolicLink() ||
+        opened.nlink !== 1 || named.nlink !== 1 ||
+        opened.dev !== named.dev || opened.ino !== named.ino) {
+      throw new Error("target must be one unchanged regular file, not a link or directory");
+    }
+    raw = readFileSync(fd, "utf8");
+    const after = lstatSync(target);
+    if (!after.isFile() || after.isSymbolicLink() || after.nlink !== 1 ||
+        after.dev !== opened.dev || after.ino !== opened.ino) {
+      throw new Error("target changed while it was read");
+    }
+    settings = JSON.parse(raw);
+  } catch (error) {
+    console.error("Refusing to touch " + target + ": " + error.message);
+    process.exit(1);
+  } finally {
+    if (fd !== null) try { closeSync(fd); } catch { /* ignore */ }
+  }
+}
+
+function validateSettings(value) {
+  if (!isObject(value)) return "settings root must be a JSON object";
+  if (value.hooks !== undefined && !isObject(value.hooks)) return "hooks must be a JSON object";
+  if (value.hooks && value.hooks.Stop !== undefined && !Array.isArray(value.hooks.Stop)) return "hooks.Stop must be an array";
+  const groups = (value.hooks && value.hooks.Stop) || [];
+  for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+    const group = groups[groupIndex];
+    if (!isObject(group)) return "hooks.Stop[" + groupIndex + "] must be an object";
+    if (!Array.isArray(group.hooks)) return "hooks.Stop[" + groupIndex + "].hooks must be an array";
+    for (let hookIndex = 0; hookIndex < group.hooks.length; hookIndex++) {
+      if (!isObject(group.hooks[hookIndex])) {
+        return "hooks.Stop[" + groupIndex + "].hooks[" + hookIndex + "] must be an object";
+      }
+    }
+  }
+  return null;
+}
+
+const shapeError = validateSettings(settings);
+if (shapeError) {
+  console.error("Refusing to touch " + target + ": " + shapeError + ".");
+  process.exit(1);
+}
+
+const quote = (value) => {
+  if (process.platform === "win32") return '"' + String(value).replace(/"/g, '""') + '"';
+  return "'" + String(value).replace(/'/g, "'\\''") + "'";
+};
+const command = quote(process.execPath) + " " + quote(script) + " " + MANAGED_MARKER +
+  (scope ? " --scope " + scope : "");
+
+const isOurHandler = (handler) => {
+  if (!isObject(handler) || typeof handler.command !== "string") return false;
+  const value = handler.command;
+  const token = (name) => new RegExp("(?:^|\\s)" + name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "(?=\\s|$)").test(value);
+  // An exact foreign --unlazy-* option is positive evidence that this is not
+  // our legacy entry, even when it happens to invoke the same script path.
+  const foreignUnlazyOption = value.split(/\s+/).some((part) => {
+    const quoted = part.length >= 2 &&
+      ((part[0] === '"' && part[part.length - 1] === '"') ||
+       (part[0] === "'" && part[part.length - 1] === "'"));
+    const option = quoted ? part.slice(1, -1) : part;
+    return option.startsWith("--unlazy-") && option !== MANAGED_MARKER;
+  });
+  if (foreignUnlazyOption) return false;
+  if (token(MANAGED_MARKER)) return true;
+  // Migrate v2.0/v2.1 handlers only when both the exact old marker and the
+  // packaged scripts/stop-hook.mjs shape are present. Substrings such as
+  // --unlazy-helper and unrelated same-named scripts are never ownership.
+  const packagedStopHook = /(?:^|[\s"'])[^\s"']*[\\/]scripts[\\/]stop-hook\.mjs(?=$|[\s"'])/i.test(value);
+  const namedLegacyInstall = /[\\/]unlazy[\\/]scripts[\\/]stop-hook\.mjs(?=$|[\s"'])/i.test(value);
+  // Upstream v2.0 shipped before any marker and is recognizable only at its
+  // conventional Claude skill location. Keep that narrow compatibility path,
+  // while marker-era moved installs require the exact standalone old token.
+  const conventionalV2Path = /[\\/]\.claude[\\/]skills[\\/]unlazy[\\/]scripts[\\/]stop-hook\.mjs(?=$|[\s"'])/i.test(value);
+  return value.includes(script) || conventionalV2Path ||
+    (token("--unlazy") && (namedLegacyInstall || packagedStopHook));
+};
+
+const originalGroups = (settings.hooks && settings.hooks.Stop) || [];
+let removed = 0;
+const keptGroups = [];
+for (const group of originalGroups) {
+  const hooks = group.hooks.filter((handler) => {
+    if (!isOurHandler(handler)) return true;
+    removed++;
+    return false;
+  });
+  if (hooks.length) keptGroups.push({ ...group, hooks });
+}
+
+function nextSettings(groups) {
+  const result = { ...settings };
+  const hooks = { ...(settings.hooks || {}) };
+  if (groups.length) hooks.Stop = groups;
+  else delete hooks.Stop;
+  if (Object.keys(hooks).length) result.hooks = hooks;
+  else delete result.hooks;
+  return result;
+}
+
+function persist(value) {
+  try {
+    if (raw) writeAtomic(backup, raw);
+    writeAtomic(target, JSON.stringify(value, null, 2) + "\n");
+  } catch (error) {
+    console.error("Could not update " + target + ": " + error.message);
+    process.exit(1);
+  }
+}
+
+if (uninstall) {
+  if (!removed) {
+    console.log("Nothing to remove: no unlazy Stop hook found in " + target);
+    process.exit(0);
+  }
+  persist(nextSettings(keptGroups));
+  console.log("Removed unlazy Stop hook (" + removed + " handler(s)) from " + target + ". Sibling handlers were preserved.");
+  process.exit(0);
+}
+
+const alreadyCurrent = removed === 1 && originalGroups.some((group) =>
+  group.hooks.some((handler) => isOurHandler(handler) && handler.command === command &&
+    handler.type === "command" && handler.timeout === 20));
+if (alreadyCurrent) {
+  console.log("Already installed in " + target + " (idempotent, nothing changed).");
+  process.exit(0);
+}
+
+const entry = { hooks: [{ type: "command", command, timeout: 20 }] };
+persist(nextSettings([...keptGroups, entry]));
+console.log("Installed unlazy Stop hook into " + target + "\n" +
+  "  command: " + command + "\n" +
+  "  scope:   " + (scope ? scope : "resolved per session/pipeline") + "\n" +
+  "  backup:  " + (raw ? backup : "not needed for a new file") + "\n" +
+  "  note:    keep .unlazy/ and .unlazy-hook-state.json ignored; they are local coordination state." +
+  (shared ? "\n  warning: shared settings contain this machine's absolute Node and skill paths." : ""));

package/dist/skills/unlazy/scripts/lib/check-supervisor.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Keep a stable process-group leader alive until CHECK stdio closes.
+// Zero dependencies. Node 16+.
+
+import { spawn } from "node:child_process";
+
+const [shell, command] = process.argv.slice(2);
+if (!shell || command === undefined) {
+  console.error("unlazy-check-supervisor: expected resolved shell and CHECK command");
+  process.exit(2);
+}
+
+let child;
+let spawnError = null;
+try {
+  child = spawn(command, {
+    cwd: process.cwd(),
+    shell,
+    windowsHide: true,
+    env: process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+} catch (error) {
+  console.error("unlazy-check-supervisor: could not start CHECK: " + error.message);
+  process.exit(127);
+}
+
+// Pipe instead of inheriting descriptors directly. Node's `close` event then
+// waits for descendants that inherited the shell's stdout or stderr, keeping
+// this detached supervisor alive as the original process-group identity.
+child.stdout.pipe(process.stdout, { end: false });
+child.stderr.pipe(process.stderr, { end: false });
+child.once("error", (error) => { spawnError = error; });
+child.once("close", (code, signal) => {
+  if (spawnError) {
+    console.error("unlazy-check-supervisor: CHECK spawn failed: " + spawnError.message);
+    process.exitCode = 127;
+    return;
+  }
+  if (Number.isInteger(code)) {
+    process.exitCode = code;
+    return;
+  }
+  console.error("unlazy-check-supervisor: CHECK ended by " + (signal || "unknown signal"));
+  process.exitCode = 1;
+});