heyspex 0.2.4 → 0.2.6

package/dist/cli/hs-trash.mjs

@@ -0,0 +1,362 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-trash.ts
+import { existsSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import process2 from "node:process";
+
+// spex-console/src/lib/cli/trash.ts
+var TRASH_EXIT = { OK: 0, USAGE: 2, RUNTIME: 1, NOT_FOUND: 10 };
+var TRASH_SUBCOMMANDS = ["list", "restore", "empty"];
+var DEFAULT_RETENTION_DAYS = 30;
+function restorePathFor(trashRelPath) {
+  const normalized = trashRelPath.split("\\").join("/");
+  const slashIdx = normalized.lastIndexOf("/");
+  const dir = slashIdx === -1 ? "" : normalized.slice(0, slashIdx);
+  const name = slashIdx === -1 ? normalized : normalized.slice(slashIdx + 1);
+  const parentDir = dir.replace(/(^|\/)\.trash$/, "");
+  const basename = name.replace(TRASH_STAMP_RE, "");
+  return parentDir ? `${parentDir}/${basename}` : basename;
+}
+var TRASH_STAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:-\d{3})?Z-/;
+function trashedAtFrom(name) {
+  const m = TRASH_STAMP_RE.exec(name);
+  if (!m) return null;
+  const stamp = m[0].slice(0, -1);
+  const iso = stamp.replace(
+    /T(\d{2})-(\d{2})-(\d{2})(?:-(\d{3}))?Z$/,
+    (_all, h, min, sec, ms) => `T${h}:${min}:${sec}${ms ? `.${ms}` : ""}Z`
+  );
+  const parsed = new Date(iso);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function ageDaysFrom(trashedAt, now) {
+  if (!trashedAt) return null;
+  return Math.max(0, Math.floor((now.getTime() - trashedAt.getTime()) / 864e5));
+}
+function parseTrashArgs(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) return { help: true };
+  let json = false;
+  let yes = false;
+  let dryRun = false;
+  let olderThanDays;
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") json = true;
+    else if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--older-than" || arg.startsWith("--older-than=")) {
+      const v = arg.startsWith("--older-than=") ? arg.slice("--older-than=".length) : argv[++i];
+      if (v === void 0) {
+        return {
+          error: { message: "--older-than requires a number of days", code: TRASH_EXIT.USAGE }
+        };
+      }
+      const days = Number(v);
+      if (!Number.isFinite(days) || days < 0) {
+        return {
+          error: {
+            message: `--older-than must be a number of days (got "${v}")`,
+            code: TRASH_EXIT.USAGE
+          }
+        };
+      }
+      olderThanDays = days;
+    } else if (arg.startsWith("-")) {
+      return { error: { message: `unknown flag: ${arg}`, code: TRASH_EXIT.USAGE } };
+    } else positionals.push(arg);
+  }
+  const sub = positionals[0] ?? "list";
+  if (!TRASH_SUBCOMMANDS.includes(sub)) {
+    return {
+      error: {
+        message: `unknown subcommand "${sub}" (expected: ${TRASH_SUBCOMMANDS.join(" | ")})`,
+        code: TRASH_EXIT.USAGE
+      }
+    };
+  }
+  const target = positionals[1];
+  if (positionals.length > 2) {
+    return { error: { message: `unexpected argument: ${positionals[2]}`, code: TRASH_EXIT.USAGE } };
+  }
+  if (sub === "restore" && !target) {
+    return {
+      error: {
+        message: "restore needs a file (e.g. hs trash restore <name>)",
+        code: TRASH_EXIT.USAGE
+      }
+    };
+  }
+  if (sub !== "restore" && target) {
+    return { error: { message: `${sub} takes no file argument`, code: TRASH_EXIT.USAGE } };
+  }
+  if (olderThanDays !== void 0 && sub !== "empty") {
+    return { error: { message: "--older-than only applies to empty", code: TRASH_EXIT.USAGE } };
+  }
+  return { args: { subcommand: sub, target, olderThanDays, yes, dryRun, json } };
+}
+function selectForEmpty(entries, olderThanDays) {
+  if (olderThanDays === void 0) return [...entries];
+  return entries.filter((e) => e.ageDays !== null && e.ageDays >= olderThanDays);
+}
+function matchEntries(entries, target) {
+  const needle = target.trim().toLowerCase();
+  if (!needle) return [];
+  const exact = entries.filter(
+    (e) => e.name.toLowerCase() === needle || e.relPath.toLowerCase() === needle
+  );
+  if (exact.length) return exact;
+  return entries.filter(
+    (e) => e.name.toLowerCase().includes(needle) || e.restoreRelPath.toLowerCase().includes(needle)
+  );
+}
+function humanSize(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)}K`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+}
+function humanAge(entry) {
+  if (entry.ageDays === null) return "age unknown";
+  if (entry.ageDays === 0) return "today";
+  if (entry.ageDays === 1) return "1 day ago";
+  return `${entry.ageDays} days ago`;
+}
+function formatTrashList(entries) {
+  if (!entries.length) return "Trash is empty.";
+  const total = entries.reduce((sum, e) => sum + e.sizeBytes, 0);
+  const wName = Math.max(...entries.map((e) => e.restoreRelPath.length));
+  const lines = entries.map(
+    (e) => `  ${e.restoreRelPath.padEnd(wName)}  ${humanAge(e).padEnd(14)} ${humanSize(e.sizeBytes)}`
+  );
+  const oldest = entries.reduce(
+    (max, e) => e.ageDays !== null && e.ageDays > max ? e.ageDays : max,
+    0
+  );
+  return [
+    `${entries.length} item(s) in the trash \xB7 ${humanSize(total)} \xB7 oldest ${oldest} days`,
+    ...lines,
+    "",
+    // Preview leads. The first version of this footer offered two ways to
+    // destroy and never named --dry-run, so the one safe option was missing
+    // from the exact place someone looks for it.
+    "  see what a clear takes:  hs trash empty --dry-run",
+    "  put one back:            hs trash restore <name>",
+    `  clear the old:           hs trash empty --older-than ${DEFAULT_RETENTION_DAYS} --yes`,
+    "  clear it all:            hs trash empty --yes"
+  ].join("\n");
+}
+var TRASH_HELP = [
+  "hs trash \u2014 the bin every spec delete soft-deletes into",
+  "",
+  "Usage:",
+  "  hs trash [list] [--json]              Show what is in the bin, and how old",
+  "  hs trash restore <name>               Put one file back where it came from",
+  "  hs trash empty [--older-than <days>] [--yes] [--dry-run]",
+  "",
+  "Deleting a spec never unlinks it \u2014 it moves to `<folder>/.trash/` with a",
+  "timestamp on the name, per the destructive-action checklist. That part has",
+  "always worked. What was missing was any way to SEE the result, so every spec",
+  "ever deleted is still on disk. This is the bin those files were going into.",
+  "",
+  "`empty` is confirm-first: with no --yes it prints what would go and removes",
+  "nothing. `--older-than <days>` limits it to entries past that age, which is",
+  "the form worth running on a schedule. An entry whose timestamp cannot be read",
+  "has an unknown age and is never swept by an age-filtered empty \u2014 it only goes",
+  "on a full `hs trash empty --yes`.",
+  "",
+  "`restore` puts a file back at its original path with the timestamp stripped,",
+  "and refuses if something already lives there rather than overwriting it.",
+  "",
+  "Nothing auto-empties today. Recommended: run",
+  `  hs trash empty --older-than ${DEFAULT_RETENTION_DAYS} --yes`,
+  "on a schedule \u2014 the same retention shape `scripts/backup-coordinator-state.mjs`",
+  "already uses for coordinator-state backups.",
+  "",
+  "This is the VAULT bin only. Handoff lanes have no trash \u2014 a lane is",
+  "coordination that self-purges on a TTL, and `hs handoff delete` hands the row",
+  "back as its own undo. Coordinator-state backups purge on their own schedule.",
+  "",
+  "Flags:",
+  "  --older-than <days>  Only entries at least this old (empty only).",
+  "  --yes, -y            Confirm an empty. Without it, empty prints and refuses.",
+  "  --dry-run            Print what would go, touch nothing.",
+  "  --json               Machine-readable output.",
+  "  --help, -h           Show this help."
+].join("\n");
+
+// spex-console/bin/run-entry.ts
+import process from "node:process";
+var BinExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "BinExit";
+    this.code = code;
+  }
+};
+function runEntry(name, main2, options = {}) {
+  const { fallbackCode = 1, unhandledLabel = "unhandled" } = options;
+  void (async () => {
+    try {
+      await main2();
+    } catch (err) {
+      if (err instanceof BinExit) {
+        process.exitCode = err.code;
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`${name}: ${unhandledLabel}: ${message}
+`);
+      process.exitCode = fallbackCode;
+    }
+  })();
+}
+
+// spex-console/bin/hs-trash.ts
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".next"]);
+function scanTrash(root, now) {
+  const found = [];
+  function walk(dir, inTrash) {
+    let dirents;
+    try {
+      dirents = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const dirent of dirents) {
+      const full = path.join(dir, dirent.name);
+      if (dirent.isDirectory()) {
+        if (SKIP_DIRS.has(dirent.name)) continue;
+        walk(full, inTrash || dirent.name === ".trash");
+        continue;
+      }
+      if (!inTrash || !dirent.isFile()) continue;
+      const relPath = path.relative(root, full).split("\\").join("/");
+      const trashedAt = trashedAtFrom(dirent.name);
+      let sizeBytes = 0;
+      try {
+        sizeBytes = statSync(full).size;
+      } catch {
+      }
+      found.push({
+        relPath,
+        name: dirent.name,
+        restoreRelPath: restorePathFor(relPath),
+        trashedAt,
+        ageDays: ageDaysFrom(trashedAt, now),
+        sizeBytes
+      });
+    }
+  }
+  walk(root, false);
+  return found.sort((a, b) => (b.ageDays ?? -1) - (a.ageDays ?? -1));
+}
+function main() {
+  const raw = process2.argv.slice(2);
+  const argv = raw[0] === "trash" ? raw.slice(1) : raw;
+  const parsed = parseTrashArgs(argv);
+  if (parsed.help) {
+    process2.stdout.write(`${TRASH_HELP}
+`);
+    process2.exitCode = TRASH_EXIT.OK;
+    return;
+  }
+  if (parsed.error) {
+    process2.stderr.write(`hs trash: ${parsed.error.message}
+`);
+    process2.exitCode = parsed.error.code;
+    return;
+  }
+  const args = parsed.args;
+  const vaultRoot = process2.env.HS_VAULT_ROOT;
+  if (!vaultRoot) {
+    process2.stderr.write(
+      "hs trash: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
+    );
+    process2.exitCode = TRASH_EXIT.USAGE;
+    return;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const entries = scanTrash(vaultRoot, now);
+  if (args.subcommand === "list") {
+    process2.stdout.write(`${args.json ? JSON.stringify({ entries }) : formatTrashList(entries)}
+`);
+    process2.exitCode = TRASH_EXIT.OK;
+    return;
+  }
+  if (args.subcommand === "restore") {
+    const matches = matchEntries(entries, args.target);
+    if (matches.length === 0) {
+      process2.stderr.write(`hs trash: nothing in the trash matches "${args.target}".
+`);
+      process2.exitCode = TRASH_EXIT.NOT_FOUND;
+      return;
+    }
+    if (matches.length > 1) {
+      process2.stderr.write(
+        `hs trash: "${args.target}" matches ${matches.length} entries:
+` + matches.map((m) => `  ${m.name}`).join("\n") + "\n  Name one exactly.\n"
+      );
+      process2.exitCode = TRASH_EXIT.USAGE;
+      return;
+    }
+    const entry = matches[0];
+    const from = path.join(vaultRoot, entry.relPath);
+    const to = path.join(vaultRoot, entry.restoreRelPath);
+    if (existsSync(to)) {
+      process2.stderr.write(
+        `hs trash: ${entry.restoreRelPath} already exists \u2014 restoring would overwrite it.
+`
+      );
+      process2.exitCode = TRASH_EXIT.USAGE;
+      return;
+    }
+    renameSync(from, to);
+    process2.stdout.write(
+      `${args.json ? JSON.stringify({ ok: true, restored: entry.restoreRelPath, from: entry.relPath }) : `Restored ${entry.restoreRelPath}
+  from ${entry.relPath}`}
+`
+    );
+    process2.exitCode = TRASH_EXIT.OK;
+    return;
+  }
+  const doomed = selectForEmpty(entries, args.olderThanDays);
+  const scope = args.olderThanDays === void 0 ? "everything in the trash" : `entries at least ${args.olderThanDays} days old`;
+  if (doomed.length === 0) {
+    process2.stdout.write(`Nothing to empty \u2014 no ${scope}.
+`);
+    process2.exitCode = TRASH_EXIT.OK;
+    return;
+  }
+  const totalBytes = doomed.reduce((sum, e) => sum + e.sizeBytes, 0);
+  const listing = doomed.map((e) => `  ${e.restoreRelPath}  (${e.ageDays ?? "?"}d)`).join("\n");
+  if (!args.yes || args.dryRun) {
+    process2.stdout.write(
+      `${args.dryRun ? "[dry-run] would permanently delete" : "Would permanently delete"} ${doomed.length} item(s) \u2014 ${scope}:
+${listing}
+  This is permanent. They were soft-deleted once already, so there is no
+  second bin behind this one.
+` + (args.dryRun ? "" : `  do it with: hs trash empty${args.olderThanDays !== void 0 ? ` --older-than ${args.olderThanDays}` : ""} --yes
+`)
+    );
+    process2.exitCode = args.dryRun ? TRASH_EXIT.OK : TRASH_EXIT.USAGE;
+    return;
+  }
+  let removed = 0;
+  for (const entry of doomed) {
+    try {
+      rmSync(path.join(vaultRoot, entry.relPath));
+      removed++;
+    } catch {
+    }
+  }
+  process2.stdout.write(
+    `${args.json ? JSON.stringify({ ok: true, removed, requested: doomed.length, bytes: totalBytes }) : `Emptied ${removed} of ${doomed.length} item(s) \u2014 ${scope}.
+  Run \`hs trash empty --older-than ${DEFAULT_RETENTION_DAYS} --yes\` on a schedule to keep it from piling up.`}
+`
+  );
+  process2.exitCode = TRASH_EXIT.OK;
+}
+runEntry("hs trash", main, { fallbackCode: TRASH_EXIT.RUNTIME });

package/dist/cli/hs-trust.mjs

@@ -0,0 +1,197 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-trust.ts
+import process3 from "node:process";
+
+// spex-console/src/lib/cli/trust-cli.ts
+import path3 from "node:path";
+
+// spex-console/src/lib/cli/folder-trust.ts
+import { realpathSync } from "node:fs";
+import path2 from "node:path";
+
+// scripts/lib/heyspex-home.mjs
+import { homedir } from "node:os";
+function heyspexHome(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir();
+}
+
+// vendor/heyspex-mcp/folder-trust-store.mjs
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+var TRUST_STORE_REL = path.join(".heyspex", "trusted-folders.json");
+function trustStorePath(home = heyspexHome()) {
+  return path.join(home, TRUST_STORE_REL);
+}
+function readTrustStore(filePath = trustStorePath()) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function writeTrustStore(store, filePath = trustStorePath()) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(store, null, 2)}
+`, "utf8");
+}
+function listTrustedFolders(store) {
+  return Object.entries(store).map(([key, entry]) => ({
+    path: key,
+    trusted: entry.trusted,
+    decidedAt: entry.decidedAt
+  }));
+}
+
+// spex-console/src/lib/cli/folder-trust.ts
+function trustStorePath2(home) {
+  return trustStorePath(home);
+}
+function trustKeyForCwd(cwd, realpathFn = realpathSync) {
+  try {
+    return realpathFn(cwd);
+  } catch {
+    return path2.resolve(cwd);
+  }
+}
+function revokeFolderTrust({
+  cwd,
+  store,
+  realpathFn
+}) {
+  if (cwd === void 0 || cwd === null) return {};
+  const key = trustKeyForCwd(cwd, realpathFn);
+  const next = { ...store };
+  delete next[key];
+  return next;
+}
+function readTrustStore2(filePath = trustStorePath2()) {
+  return readTrustStore(filePath);
+}
+function writeTrustStore2(store, filePath = trustStorePath2()) {
+  writeTrustStore(store, filePath);
+}
+function listTrustedFolders2(store) {
+  return listTrustedFolders(store);
+}
+
+// spex-console/src/lib/cli/trust-cli.ts
+var EXIT = {
+  /** Success. */
+  OK: 0,
+  /** Usage error — an unknown subcommand/argument. */
+  USAGE: 1
+};
+var TRUST_HELP = [
+  "hs trust \u2014 list / revoke spexcode's stored folder-trust decisions",
+  "",
+  "  hs trust list                 List every stored decision: path, trusted yes/no, decidedAt",
+  "  hs trust revoke [path]        Clear one folder's decision (default: cwd) \u2014 the next",
+  "                                 `spexcode` launch there asks again",
+  "  hs trust --help                Show this help",
+  "",
+  "Store: ~/.heyspex/trusted-folders.json \u2014 machine-local, never part of the vault."
+].join("\n");
+function runTrustCommand(argv, options = {}) {
+  if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
+    return { code: EXIT.OK, stdout: `${TRUST_HELP}
+`, stderr: "" };
+  }
+  const cwd = options.cwd ?? process.cwd();
+  const storePath = options.storePath ?? trustStorePath2();
+  const [sub, ...rest] = argv;
+  if (sub === "list") {
+    if (rest.length > 0) {
+      return {
+        code: EXIT.USAGE,
+        stdout: "",
+        stderr: `hs trust list: unknown argument: ${rest[0]}
+`
+      };
+    }
+    const rows = listTrustedFolders2(readTrustStore2(storePath));
+    const header = `Trusted-folder store: ${storePath}
+`;
+    if (rows.length === 0) {
+      return { code: EXIT.OK, stdout: `${header}(no stored trust decisions)
+`, stderr: "" };
+    }
+    const body = rows.slice().sort((a, b) => a.path.localeCompare(b.path)).map((r) => `  ${r.trusted ? "trusted    " : "not trusted"}  ${r.decidedAt}  ${r.path}`).join("\n");
+    return { code: EXIT.OK, stdout: `${header}${body}
+`, stderr: "" };
+  }
+  if (sub === "revoke") {
+    if (rest.length > 1) {
+      return {
+        code: EXIT.USAGE,
+        stdout: "",
+        stderr: `hs trust revoke: unknown argument: ${rest[1]}
+`
+      };
+    }
+    const target = rest[0] ? path3.resolve(cwd, rest[0]) : cwd;
+    const next = revokeFolderTrust({ cwd: target, store: readTrustStore2(storePath) });
+    writeTrustStore2(next, storePath);
+    return {
+      code: EXIT.OK,
+      stdout: `hs trust: trust decision cleared for "${target}" (${storePath}). The next launch there will ask again.
+`,
+      stderr: ""
+    };
+  }
+  return {
+    code: EXIT.USAGE,
+    stdout: "",
+    stderr: `hs trust: unknown subcommand "${sub}" (try "hs trust --help")
+`
+  };
+}
+
+// spex-console/bin/run-entry.ts
+import process2 from "node:process";
+var BinExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "BinExit";
+    this.code = code;
+  }
+};
+function runEntry(name, main2, options = {}) {
+  const { fallbackCode = 1, unhandledLabel = "unhandled" } = options;
+  void (async () => {
+    try {
+      await main2();
+    } catch (err) {
+      if (err instanceof BinExit) {
+        process2.exitCode = err.code;
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      process2.stderr.write(`${name}: ${unhandledLabel}: ${message}
+`);
+      process2.exitCode = fallbackCode;
+    }
+  })();
+}
+
+// spex-console/bin/hs-trust.ts
+function main() {
+  const invokedCwd = process3.env.HS_INVOKED_CWD?.trim() || process3.cwd();
+  const result = runTrustCommand(process3.argv.slice(3), {
+    cwd: invokedCwd,
+    storePath: process3.env.HS_TRUST_STORE_PATH || void 0
+  });
+  if (result.stdout) process3.stdout.write(result.stdout);
+  if (result.stderr) process3.stderr.write(result.stderr);
+  process3.exitCode = result.code;
+}
+runEntry("hs trust", main, { fallbackCode: EXIT.USAGE });