toolroll 0.5.0

package/dist/project.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Projects, as the console means them: a project IS a repo path on this
+ * server — one row of truth, no new concept — and, critically, project
+ * *selection* is never project *authorization*.
+ *
+ * The ceiling is server configuration: the repos named at startup, plus any
+ * git repository under a configured project root. A session picking a
+ * project picks from inside that ceiling; a registry row, a store row, or a
+ * request header can name a path, but naming is not access (per the v2
+ * review's first finding). No configuration at all is the legacy unscoped
+ * mode — everything visible — and the code says so where it decides.
+ */
+import { type ExecResult, type RunOptions } from "./exec.js";
+export type ProjectExec = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+/**
+ * One canonicalization for every path that becomes project identity:
+ * startup config, a session open, task placement. Comparisons elsewhere
+ * fall back to raw equality for legacy rows written before this existed.
+ */
+export declare function canonicalProject(path: string): string | null;
+/** Two repo identities, canonical when possible, raw-equal as the legacy fallback. */
+export declare function sameRepo(a: string | null, b: string | null): boolean;
+/** Whether this path is actually a git repository — direct argv, bounded, no shell. */
+export declare function isGitRepo(path: string, exec?: ProjectExec): Promise<boolean>;
+/** Validate a whole selection before enrolling anything; subfolders resolve to their checkout root. */
+export declare function projectSelection(paths: readonly string[], exec?: ProjectExec): Promise<string[]>;
+export type ProjectCeiling = {
+    /** Canonical repo paths named at startup. */
+    repos: readonly string[];
+    /** Canonical directories: any git repo under one is authorized. */
+    roots: readonly string[];
+};
+/**
+ * Resolve the startup configuration once. A configured path that does not
+ * currently resolve is kept in its normalized form rather than dropped —
+ * dropping would silently *widen* the server toward unscoped mode, and a
+ * ceiling that loosens itself when a disk is unmounted is not a ceiling.
+ */
+export declare function resolveCeiling(repos: readonly string[], roots: readonly string[]): {
+    ceiling: ProjectCeiling;
+    unresolved: string[];
+};
+/** Whether the ceiling is even configured. Unconfigured = legacy unscoped mode. */
+export declare function unscoped(ceiling: ProjectCeiling): boolean;
+/**
+ * The authorization question, answered from configuration alone. A path
+ * under a root must additionally BE a git repository — a root authorizes
+ * its repos, not every directory beneath it — which is why this is async.
+ */
+export declare function authorizedProject(ceiling: ProjectCeiling, path: string, exec?: ProjectExec): Promise<boolean>;
+/**
+ * The cheap synchronous subset for per-row visibility checks: a row whose
+ * repo is NULL (unplaced) is always visible; a named repo must match the
+ * configured set or live under a root. The under-a-root case skips the
+ * git check here — rows only enter the store through placement, which
+ * validated them; this guards reads, and a non-repo directory under an
+ * authorized root read-visible is a smaller wrong than an async row filter.
+ */
+export declare function rowVisible(ceiling: ProjectCeiling, repo: string | null): boolean;
+/** A display name for a project: its basename, the way people say it. */
+export declare function projectName(path: string): string;

package/dist/project.js

@@ -0,0 +1,125 @@
+/**
+ * Projects, as the console means them: a project IS a repo path on this
+ * server — one row of truth, no new concept — and, critically, project
+ * *selection* is never project *authorization*.
+ *
+ * The ceiling is server configuration: the repos named at startup, plus any
+ * git repository under a configured project root. A session picking a
+ * project picks from inside that ceiling; a registry row, a store row, or a
+ * request header can name a path, but naming is not access (per the v2
+ * review's first finding). No configuration at all is the legacy unscoped
+ * mode — everything visible — and the code says so where it decides.
+ */
+import { realpathSync, statSync } from "node:fs";
+import { basename, resolve, sep } from "node:path";
+import { run } from "./exec.js";
+/**
+ * One canonicalization for every path that becomes project identity:
+ * startup config, a session open, task placement. Comparisons elsewhere
+ * fall back to raw equality for legacy rows written before this existed.
+ */
+export function canonicalProject(path) {
+    try {
+        const real = realpathSync(resolve(path));
+        return statSync(real).isDirectory() ? real : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Two repo identities, canonical when possible, raw-equal as the legacy fallback. */
+export function sameRepo(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    if (a === b)
+        return true;
+    const ca = canonicalProject(a);
+    const cb = canonicalProject(b);
+    return ca !== null && ca === cb;
+}
+/** Whether this path is actually a git repository — direct argv, bounded, no shell. */
+export async function isGitRepo(path, exec = run) {
+    const result = await exec("git", ["rev-parse", "--git-dir"], { cwd: path, timeoutMs: 5_000 });
+    return result.code === 0;
+}
+/** Validate a whole selection before enrolling anything; subfolders resolve to their checkout root. */
+export async function projectSelection(paths, exec = run) {
+    if (paths.length === 0 || paths.length > 50)
+        throw new Error("Choose between 1 and 50 project folders.");
+    const repos = new Set();
+    for (const path of paths) {
+        if (!path.trim() || path.length > 4096)
+            throw new Error("Choose a valid project folder.");
+        const canonical = canonicalProject(path);
+        if (canonical === null)
+            throw new Error(`This folder is unavailable: ${path}`);
+        const result = await exec("git", ["rev-parse", "--show-toplevel"], { cwd: canonical, timeoutMs: 5000 });
+        const root = result.code === 0 ? canonicalProject(result.stdout.trim()) : null;
+        if (root === null)
+            throw new Error(`This folder is not a Git project: ${path}`);
+        repos.add(root);
+    }
+    return [...repos];
+}
+/**
+ * Resolve the startup configuration once. A configured path that does not
+ * currently resolve is kept in its normalized form rather than dropped —
+ * dropping would silently *widen* the server toward unscoped mode, and a
+ * ceiling that loosens itself when a disk is unmounted is not a ceiling.
+ */
+export function resolveCeiling(repos, roots) {
+    const unresolved = [];
+    const keep = (paths) => [...new Set(paths.map(path => {
+            const canonical = canonicalProject(path);
+            if (canonical !== null)
+                return canonical;
+            unresolved.push(path);
+            return resolve(path);
+        }))];
+    return { ceiling: { repos: keep(repos), roots: keep(roots) }, unresolved };
+}
+/** Whether the ceiling is even configured. Unconfigured = legacy unscoped mode. */
+export function unscoped(ceiling) {
+    return ceiling.repos.length === 0 && ceiling.roots.length === 0;
+}
+/**
+ * The authorization question, answered from configuration alone. A path
+ * under a root must additionally BE a git repository — a root authorizes
+ * its repos, not every directory beneath it — which is why this is async.
+ */
+export async function authorizedProject(ceiling, path, exec = run) {
+    if (unscoped(ceiling))
+        return true;
+    const canonical = canonicalProject(path);
+    if (canonical === null)
+        return false;
+    if (ceiling.repos.includes(canonical))
+        return true;
+    for (const root of ceiling.roots) {
+        if (canonical.startsWith(root + sep) && (await isGitRepo(canonical, exec)))
+            return true;
+    }
+    return false;
+}
+/**
+ * The cheap synchronous subset for per-row visibility checks: a row whose
+ * repo is NULL (unplaced) is always visible; a named repo must match the
+ * configured set or live under a root. The under-a-root case skips the
+ * git check here — rows only enter the store through placement, which
+ * validated them; this guards reads, and a non-repo directory under an
+ * authorized root read-visible is a smaller wrong than an async row filter.
+ */
+export function rowVisible(ceiling, repo) {
+    if (repo === null || unscoped(ceiling))
+        return true;
+    // Exact saved identities are common. Check the whole set before resolving
+    // aliases, so the hundredth project does not stat the other99 directories.
+    if (ceiling.repos.includes(repo) || ceiling.repos.some(one => sameRepo(one, repo)))
+        return true;
+    const canonical = canonicalProject(repo) ?? repo;
+    return ceiling.roots.some(root => canonical.startsWith(root + sep));
+}
+/** A display name for a project: its basename, the way people say it. */
+export function projectName(path) {
+    return basename(path);
+}

package/dist/prompt.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Interactive prompts, for exactly one situation: a person at a real
+ * terminal left out a value a command needs. Every prompt is gated on a
+ * TTY at both ends and never fires under --json — an agent or a cron job
+ * gets the same immediate usage refusal as always, because a scheduler
+ * hanging on "password:" at 3am is the one bug this module must not have.
+ */
+/** Whether asking is even possible: a human on both ends of the pipe. */
+export declare function interactive(): boolean;
+export declare function ask(question: string): Promise<string>;
+/** Like ask, but what is typed never echoes — passwords live here. */
+/**
+ * Raw-mode input is not text: a terminal with bracketed paste on wraps a
+ * pasted password in ESC[200~ … ESC[201~, and any arrow or function key
+ * arrives as an escape sequence. Every CSI/SS3 sequence is dropped whole,
+ * so a pasted secret compares equal to a typed one (setup review: the
+ * hidden prompt refused every pasted password on iTerm and Terminal.app).
+ */
+export declare function sanitizeHiddenInput(text: string): string;
+export declare function askHidden(question: string): Promise<string>;
+/** A yes/no gate for an act worth a beat of deliberateness. */
+export declare function confirm(question: string): Promise<boolean>;

package/dist/prompt.js

@@ -0,0 +1,72 @@
+/**
+ * Interactive prompts, for exactly one situation: a person at a real
+ * terminal left out a value a command needs. Every prompt is gated on a
+ * TTY at both ends and never fires under --json — an agent or a cron job
+ * gets the same immediate usage refusal as always, because a scheduler
+ * hanging on "password:" at 3am is the one bug this module must not have.
+ */
+import { createInterface } from "node:readline";
+/** Whether asking is even possible: a human on both ends of the pipe. */
+export function interactive() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+export function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => rl.question(question, answer => {
+        rl.close();
+        resolve(answer.trim());
+    }));
+}
+/** Like ask, but what is typed never echoes — passwords live here. */
+/**
+ * Raw-mode input is not text: a terminal with bracketed paste on wraps a
+ * pasted password in ESC[200~ … ESC[201~, and any arrow or function key
+ * arrives as an escape sequence. Every CSI/SS3 sequence is dropped whole,
+ * so a pasted secret compares equal to a typed one (setup review: the
+ * hidden prompt refused every pasted password on iTerm and Terminal.app).
+ */
+export function sanitizeHiddenInput(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\u001bO[@-~]/g, "").replace(/\u001b/g, "");
+}
+export function askHidden(question) {
+    process.stdout.write(question);
+    const stdin = process.stdin;
+    const wasRaw = stdin.isRaw === true;
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    return new Promise(resolve => {
+        let value = "";
+        const finish = () => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode?.(wasRaw);
+            stdin.pause();
+            process.stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            const text = sanitizeHiddenInput(chunk.toString("utf8"));
+            for (const ch of text) {
+                if (ch === "\r" || ch === "\n" || ch === "\u0004") {
+                    finish();
+                    resolve(value);
+                    return;
+                }
+                if (ch === "\u0003") {
+                    // Ctrl-C during a hidden prompt: leave the terminal usable, then go.
+                    finish();
+                    process.exit(130);
+                }
+                if (ch === "\u007f" || ch === "\b")
+                    value = value.slice(0, -1);
+                else if (ch >= " ")
+                    value += ch;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+/** A yes/no gate for an act worth a beat of deliberateness. */
+export async function confirm(question) {
+    const answer = await ask(`${question} (yes/no) `);
+    return answer.toLowerCase() === "yes" || answer.toLowerCase() === "y";
+}