@vincemakes/kiso-code 0.39.2 → 0.40.0

package/dist/session-migration.js

@@ -0,0 +1,319 @@
+/**
+ * 0.40.0 — the one-time move of the legacy `KISO_HOME/sessions` into the
+ * per-project folders (see projects.ts). The lead's conditions, in order:
+ *
+ *   1. the manifest is written FIRST: every session's old folder, new
+ *      folder, reason and evidence, before any file moves;
+ *   2. a session whose lock a live process holds is skipped, and moved on a
+ *      later start;
+ *   3. a recorded workspace places a session; otherwise the paths its tools
+ *      touched, mapped to their repository on disk, place it when one root
+ *      has at least 3 mentions and 80% of them; anything else goes to
+ *      `_unknown`. A delegated child follows its parent;
+ *   4. the move is announced once, naming the reverse command.
+ *
+ * Each session moves trace → sidecar → lock → log (projects.ts), so a crash
+ * leaves the log in the legacy folder, where the next start finds it again.
+ * Nothing is deleted: files the move does not own (orphan sidecars, the
+ * delegation artifacts, whose paths the parents' logs record) stay where
+ * they are.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { readProfile } from "@vincemakes/kiso-runtime/internal";
+import { canonicalPath, claimProjectDir, hasSession, LEGACY_SESSIONS_DIR, lockHeldLive, moveSessionFiles, parentOfChild, projectDirFor, PROJECTS_DIR, REVERSED_MARKER, sessionFiles, unknownDir, } from "./projects.js";
+/** The inference's two thresholds (the lead's ruling). */
+export const INFER_MIN_MENTIONS = 3;
+export const INFER_MIN_SHARE = 0.8;
+/** The legacy sessions still to move: non-empty logs, sorted. */
+export function pendingLegacyIds(home) {
+    const dir = join(home, LEGACY_SESSIONS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.endsWith(".jsonl"))
+        .map((e) => e.slice(0, -".jsonl".length))
+        .filter((id) => hasSession(dir, id))
+        .sort();
+}
+/** An absolute path inside a tool's input or output. The leading guard
+ *  keeps a URL's path (`https://x/y`) and a relative path's tail out. */
+const ABS_PATH = /(?<![\w.:/~-])\/[^\s'"`;|&<>(){}[\],*?$\\]+/g;
+/**
+ * The repository a path belongs to: the nearest ancestor holding `.git`.
+ * A linked worktree (`.git` is a file naming `<repo>/.git/worktrees/x`)
+ * belongs to its main repository. Walks stop at the home directory, and
+ * paths inside KISO_HOME belong to no project.
+ */
+export function repoRootOf(path, cache, stops) {
+    if (path === stops.kisoHome || path.startsWith(`${stops.kisoHome}/`))
+        return null;
+    const walked = [];
+    let dir = path;
+    let root = null;
+    for (;;) {
+        const known = cache.get(dir);
+        if (known !== undefined) {
+            root = known;
+            break;
+        }
+        walked.push(dir);
+        if (dir === "/" || dir === stops.home)
+            break;
+        const git = join(dir, ".git");
+        if (existsSync(git)) {
+            root = dir;
+            try {
+                if (statSync(git).isFile()) {
+                    const m = /^gitdir:\s*(.+?)\/\.git\/worktrees\/[^/]+\s*$/m.exec(readFileSync(git, "utf8"));
+                    if (m !== null)
+                        root = m[1];
+                }
+            }
+            catch {
+                // unreadable `.git` file — the directory itself is the root
+            }
+            // as the disk spells it: a log that wrote `~/desktop/x` and one
+            // that wrote `~/Desktop/x` name one repository
+            root = canonicalPath(root);
+            break;
+        }
+        dir = dirname(dir);
+    }
+    for (const d of walked)
+        cache.set(d, root);
+    return root;
+}
+/** The absolute paths one log's tool calls and tool results name. */
+export function toolPaths(logText) {
+    const out = [];
+    for (const line of logText.split("\n")) {
+        if (line === "")
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line).event ?? {};
+        }
+        catch {
+            continue; // a torn line
+        }
+        if (event.type !== "tool_call_end" && event.type !== "tool_result")
+            continue;
+        const text = JSON.stringify(event.type === "tool_call_end" ? event.input : event.content) ?? "";
+        for (const m of text.replaceAll("\\n", "\n").replaceAll("\\t", "\t").matchAll(ABS_PATH))
+            out.push(m[0]);
+    }
+    return out;
+}
+/** The inference over one log: the dominant repository and its counts. */
+export function inferWorkspace(logText, cache, stops) {
+    const counts = new Map();
+    for (const path of toolPaths(logText)) {
+        const root = repoRootOf(path, cache, stops);
+        if (root !== null)
+            counts.set(root, (counts.get(root) ?? 0) + 1);
+    }
+    let best = null;
+    let total = 0;
+    for (const entry of counts) {
+        total += entry[1];
+        if (best === null || entry[1] > best[1])
+            best = entry;
+    }
+    if (best === null)
+        return null;
+    return { root: best[0], mentions: best[1], total, placed: best[1] >= INFER_MIN_MENTIONS && best[1] / total >= INFER_MIN_SHARE };
+}
+/**
+ * The plan: where every pending legacy session goes, and why. A pure read
+ * of the legacy folder and the repositories on disk — nothing is written,
+ * so the owner's dry run is this function over a copy.
+ */
+export function planMigration(home, opts = {}) {
+    const legacy = join(home, LEGACY_SESSIONS_DIR);
+    const ids = pendingLegacyIds(home);
+    const stops = { home: opts.userHome ?? homedir(), kisoHome: home };
+    const cache = new Map();
+    // an earlier run's decision stands: that run may have moved the sidecar
+    // (which holds the recorded workspace) and crashed before the log, and a
+    // re-decision from what is left would send the log somewhere else
+    const earlier = earlierDecisions(home);
+    const decided = new Map();
+    const decide = (id) => {
+        const done = decided.get(id);
+        if (done !== undefined)
+            return done;
+        let placement;
+        const parent = parentOfChild(id);
+        const profile = readProfile(legacy, id);
+        const recorded = profile.kind === "ok" ? profile.profile.workspace : null;
+        const prior = earlier.get(id);
+        if (lockHeldLive(legacy, id)) {
+            placement = { id, reason: "skipped-live", workspace: null, from: legacy };
+        }
+        else if (prior !== undefined) {
+            placement = { ...prior, from: legacy };
+        }
+        else if (parent !== null && ids.includes(parent)) {
+            // a child follows its parent — unless the parent is open, and then
+            // the child waits with it
+            const p = decide(parent);
+            placement = { id, reason: p.reason, workspace: p.workspace, from: legacy, parent, ...(p.evidence !== undefined ? { evidence: p.evidence } : {}) };
+        }
+        else if (recorded !== null) {
+            placement = { id, reason: "recorded", workspace: canonicalPath(recorded), from: legacy };
+        }
+        else {
+            let text = "";
+            try {
+                text = readFileSync(join(legacy, `${id}.jsonl`), "utf8");
+            }
+            catch {
+                // unreadable — no evidence, so no project
+            }
+            const inferred = inferWorkspace(text, cache, stops);
+            placement =
+                inferred !== null && inferred.placed
+                    ? { id, reason: "inferred", workspace: inferred.root, from: legacy, evidence: { root: inferred.root, mentions: inferred.mentions, total: inferred.total } }
+                    : { id, reason: "unknown", workspace: null, from: legacy, ...(inferred !== null ? { evidence: { root: inferred.root, mentions: inferred.mentions, total: inferred.total } } : {}) };
+        }
+        decided.set(id, placement);
+        return placement;
+    };
+    // the target folders, assigned in one pass so two workspaces that encode
+    // alike get distinct folders before either exists on disk
+    const taken = new Map();
+    const dirOf = new Map();
+    const target = (workspace) => {
+        if (workspace === null)
+            return unknownDir(home);
+        const known = dirOf.get(workspace);
+        if (known !== undefined)
+            return known;
+        const dir = projectDirFor(home, workspace, taken);
+        taken.set(dir, workspace);
+        dirOf.set(workspace, dir);
+        return dir;
+    };
+    const plan = ids.map((id) => {
+        const p = decide(id);
+        return { ...p, to: p.reason === "skipped-live" ? null : (p.to ?? target(p.workspace)) };
+    });
+    // children move before their parent: a crash between them leaves the
+    // parent — whose log is the one a person resumes — still listed
+    return [...plan.filter((p) => p.parent !== undefined), ...plan.filter((p) => p.parent === undefined)];
+}
+/** Every earlier manifest's placements that were not skips, the latest
+ *  first-come: id → where it was going. */
+function earlierDecisions(home) {
+    const out = new Map();
+    const dir = join(home, PROJECTS_DIR);
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.startsWith("migration-") && n.endsWith(".json"));
+    }
+    catch {
+        return out;
+    }
+    for (const name of names.sort().reverse()) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, name), "utf8"));
+            for (const e of parsed.entries ?? []) {
+                if (e.to === null || e.reason === "skipped-live" || out.has(e.id))
+                    continue;
+                out.set(e.id, e);
+            }
+        }
+        catch {
+            // an unreadable manifest decides nothing
+        }
+    }
+    return out;
+}
+export function countPlan(plan) {
+    const n = (r) => plan.filter((p) => p.reason === r).length;
+    return { recorded: n("recorded"), inferred: n("inferred"), unknown: n("unknown"), skippedLive: n("skipped-live") };
+}
+/**
+ * Run the plan. The manifest lands before the first move; after the moves
+ * it is rewritten with each entry's outcome. Returns null when there was
+ * nothing to move (all skipped, or nothing pending).
+ */
+export function runMigration(home, plan, now = new Date()) {
+    const movable = plan.filter((p) => p.to !== null);
+    if (movable.length === 0)
+        return null;
+    const root = join(home, PROJECTS_DIR);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const manifest = join(root, `migration-${now.toISOString().replace(/[:.]/g, "-")}.json`);
+    const write = (entries, completedAt) => {
+        const tmp = `${manifest}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify({ version: 1, startedAt: now.toISOString(), completedAt, entries }, null, 1)}\n`, { mode: 0o600 });
+        renameSync(tmp, manifest);
+    };
+    write(plan, null);
+    let moved = 0;
+    const outcomes = plan.map((p) => {
+        if (p.to === null)
+            return { ...p, moved: false };
+        claimProjectDir(p.to, p.workspace);
+        // a session that became open since the plan was made waits too
+        if (lockHeldLive(p.from, p.id))
+            return { ...p, moved: false, skipped: "opened during the move" };
+        moveSessionFiles(p.from, p.to, p.id);
+        const ok = hasSession(p.to, p.id) && !existsSync(join(p.from, `${p.id}.jsonl`));
+        if (ok)
+            moved += 1;
+        return { ...p, moved: ok };
+    });
+    write(outcomes, new Date().toISOString());
+    return { manifest, counts: countPlan(plan), moved };
+}
+/** The announcement, once per migration that moved something. */
+export function migrationNotice(result) {
+    const c = result.counts;
+    const parts = [`recorded ${c.recorded}`, `inferred ${c.inferred}`, `unknown ${c.unknown}`, ...(c.skippedLive > 0 ? [`still open ${c.skippedLive}, moved later`] : [])];
+    return `sessions now live in one folder per project — moved ${result.moved} (${parts.join(" · ")}); undo: kiso sessions --reverse-migration ${result.manifest}`;
+}
+/**
+ * `kiso sessions --reverse-migration <manifest>`: every entry the manifest
+ * moved goes back to the legacy folder, the log FIRST (so a crash leaves it
+ * listed from its old place), and the marker switches the per-project
+ * layout off. Sessions created in project folders after the migration are
+ * not in the manifest and stay; the count says so.
+ */
+export function reverseMigration(home, manifestPath) {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const entries = (parsed.entries ?? []).filter((e) => e.to !== null);
+    let restored = 0;
+    // parents first, then children: the reverse of the forward order
+    for (const e of [...entries.filter((x) => x.parent === undefined), ...entries.filter((x) => x.parent !== undefined)]) {
+        if (e.to === null || !existsSync(join(e.to, `${e.id}.jsonl`)))
+            continue;
+        moveSessionFiles(e.to, e.from, e.id, [...sessionFiles(e.id)].reverse());
+        if (hasSession(e.from, e.id))
+            restored += 1;
+    }
+    mkdirSync(join(home, PROJECTS_DIR), { recursive: true, mode: 0o700 });
+    writeFileSync(join(home, PROJECTS_DIR, REVERSED_MARKER), `${new Date().toISOString()} ${manifestPath}\n`, { mode: 0o600 });
+    let left = 0;
+    const root = join(home, PROJECTS_DIR);
+    for (const name of readdirSync(root)) {
+        const dir = join(root, name);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+            left += readdirSync(dir).filter((f) => f.endsWith(".jsonl") && hasSession(dir, f.slice(0, -".jsonl".length))).length;
+        }
+        catch {
+            // unreadable folder — not counted
+        }
+    }
+    return { restored, left };
+}

package/dist/shell-words.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The shell command line, READ — never run — for the approval chain
+ * (0.40.0: the read-only allow now, the catastrophe floor next).
+ *
+ * This is not a shell. It is a lexer for the subset of POSIX sh whose
+ * meaning can be known WITHOUT running anything, and it refuses the rest:
+ * a command line that uses expansion (`$`, backticks, globs, a leading
+ * `~`, braces), grouping or subshells, background jobs, heredocs, or a
+ * leading variable assignment does not parse, and a caller that cannot
+ * parse a line must treat it as unknown. The refusals are the design —
+ * every construct accepted here is one whose words are exactly the words
+ * the shell will pass to the program.
+ *
+ * What it produces is a LIST of pipelines joined by `;`, `&&`, `||` (a
+ * newline counts as `;`), each pipeline a series of simple commands joined
+ * by `|`, each command an argv plus its redirections.
+ */
+export interface Redirect {
+    /** The descriptor written before the operator (`2>`), null when none
+     *  was written, or "&" for `&>` (stdout and stderr together). */
+    readonly fd: number | "&" | null;
+    readonly op: ">" | ">>" | "<" | ">&";
+    readonly target: string;
+}
+export interface SimpleCommand {
+    readonly argv: readonly string[];
+    readonly redirects: readonly Redirect[];
+}
+export interface Pipeline {
+    /** How this pipeline joins the one before it; null for the first. */
+    readonly joinedBy: ";" | "&&" | "||" | null;
+    readonly stages: readonly SimpleCommand[];
+}
+export type ParseResult = {
+    readonly ok: true;
+    readonly list: readonly Pipeline[];
+} | {
+    readonly ok: false;
+    readonly why: string;
+};
+/**
+ * Parse a command line, or say why not. Pure: no filesystem, no
+ * environment.
+ */
+export declare function parseShell(src: string): ParseResult;
+/**
+ * A path argument, resolved the way read_file resolves one: against the
+ * directory the command runs in, with symlinks in the deepest EXISTING
+ * ancestor followed, and the not-yet-existing tail re-appended. `inside`
+ * is whether that canonical path is the workspace root or under it. One
+ * resolver for every consumer — the read-only allow asks "inside?", the
+ * floor asks "what is this?" — so the two can never disagree about where
+ * a path goes.
+ */
+export interface ResolvedPath {
+    readonly canonical: string;
+    readonly inside: boolean;
+}
+/** The well-known home subtrees that hold credentials or configuration
+ *  that runs — one list for both chain members: the read-only allow
+ *  never reads or lists under them, the floor never deletes them. */
+export declare const HOME_SUBTREES: readonly string[];
+/** A real path in the case the DISK holds it. The JS realpath keeps the
+ *  case it was given, so on a case-insensitive disk `.ENV` stayed `.ENV`
+ *  and walked past every name-based predicate (the lead's review, B2). */
+export declare function realCase(p: string): string;
+export declare function resolveShellPath(workspaceRoot: string, cwd: string, word: string): ResolvedPath;
+/**
+ * The FLOOR's reading of a command line (0.40.0 item 4) — the opposite
+ * contract to `parseShell`. The read-only allow must refuse whatever it
+ * cannot read exactly; the floor must never refuse to read, because a
+ * line it gave up on is a line it let through. So this reader accepts
+ * everything, approximately, and marks where each word stops being known:
+ *
+ *  - every simple command the line would run is returned in order,
+ *    including the ones inside `$( )`, backticks and `( )` groups;
+ *  - a word records the index where its first unknown character sits (a
+ *    variable, a substitution, an unquoted glob), whether it began with
+ *    an unquoted `~`, and whether it is ONLY a variable (`$DIR/`,
+ *    `"${X}"/*`: nothing literal but slashes, dots and globs);
+ *  - redirection targets and leading assignments are not arguments, and
+ *    are dropped.
+ */
+export interface LooseWord {
+    readonly text: string;
+    /** Index of the first unknown character, or -1 when all is literal. */
+    readonly unknownAt: number;
+    /** Whether that first unknown is a glob (`*`), not a variable or a
+     *  substitution: a glob ranges over a directory's entries, a variable
+     *  can be anything at all. */
+    readonly unknownIsGlob: boolean;
+    readonly tilde: boolean;
+    readonly variableOnly: boolean;
+}
+/** One command, and how it joins the one before it: after `cd x &&` it
+ *  runs in x, after `cd x ||` in the old directory, after `;` in either. */
+export interface LooseCommand {
+    readonly kind: "cmd";
+    readonly argv: readonly LooseWord[];
+    readonly joinedBy: "&&" | "||" | ";" | "|";
+    /** The words the reader drops — redirection targets and leading
+     *  assignments — kept only when the caller asks (`keepDropped`): the
+     *  floor judges what a command DOES, the protected-file check what a
+     *  line NAMES, and `< file` names a file. */
+    readonly dropped?: readonly LooseWord[];
+}
+/** A subshell: a `( … )` group, or the command line inside `$( … )` or
+ *  backticks (which runs BEFORE the command that holds it). A `cd` inside
+ *  one does not move the shell around it. */
+export interface LooseGroup {
+    readonly kind: "group";
+    readonly items: readonly LooseNode[];
+    readonly joinedBy: "&&" | "||" | ";" | "|";
+}
+export type LooseNode = LooseCommand | LooseGroup;
+/** B6 (the lead's review): how deep the reader follows nested subshells.
+ *  A 9 KB `$(` nest overflowed the stack; the runtime turned the throw into
+ *  an ask, bypass's allow won, and /bin/sh ran the line. Past this depth
+ *  the word is taken as only a variable — which, as a target, is refused —
+ *  and nothing deeper is read. */
+export declare const LOOSE_MAX_DEPTH = 64;
+/** Every command the line would run, in order, flattened — for a caller
+ *  that asks the same question of each one. */
+export declare function looseCommands(nodes: readonly LooseNode[]): LooseCommand[];
+export declare function parseShellLoose(src: string): LooseNode[];
+/** The same, saying whether the reader stopped short: a nest past
+ *  LOOSE_MAX_DEPTH is not read, and a caller that must see every command
+ *  (the floor) treats an unread line as one it could not read. */
+export declare function parseShellLooseChecked(src: string, opts?: {
+    readonly keepDropped?: boolean;
+}): {
+    readonly nodes: LooseNode[];
+    readonly truncated: boolean;
+};