aboutsummaryrefslogtreecommitdiffstats
path: root/cli/src/core/purpose.ts
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-12 21:55:12 +0200
committeruser <user@clank>2026-08-12 21:55:12 +0200
commit72441afa75c058e4b1454108d962f2bebaee941b (patch)
treed668f1f61d8cbf19127013724db50cf680aa59c9 /cli/src/core/purpose.ts
parentdocs: agree the sl0ppi CLI design (diff)
downloadsl0ppi-72441afa75c058e4b1454108d962f2bebaee941b.tar.gz
sl0ppi-72441afa75c058e4b1454108d962f2bebaee941b.tar.xz
sl0ppi-72441afa75c058e4b1454108d962f2bebaee941b.zip
cli: the idempotency core (discovery, tab identity, plan diff)
Slice 1 of docs/cli-design.md: the only part with logic worth testing hard. Pure functions, no subprocesses, so the tests hit them directly. purpose.ts tab identity as a zellij tab purpose carrying the project's root-relative path discover.ts depth-1 scan for .sl0ppi/ markers plan.ts discovered projects vs list-tabs -> {create, close, keep, foreign} Identity carries the *path* because `list-panes --json` exposes no cwd (checked against a live session, not assumed), so there is otherwise no way back from a tab to a directory on disk. Slashes survive the fork's sanitiser, so nested paths encode fine. Two safety properties, both fuzzed over 5000 random names: - a purpose never exceeds 64 chars and always survives re-sanitising, so what we generate is what the terminal stores - projectRelPath() reconstructs the original path exactly or returns null -- never a different path. Wrong answers close the wrong tab; refusing only leaves a stale one. The fuzz caught a real bug in the second property. The first implementation detected lossy encodings by re-encoding and comparing, which silently failed: `project:<47 a's>.<hash8>` is itself 64 legal characters, so it re-encodes to itself, the check passed, and a bogus path was "reconstructed" -- which would have closed a live tab. Lossy purposes now carry a structural marker (a leading dot, which no discovered path can have) instead of relying on a comparison. Plus the mount guard from the design: when the ROOT itself is missing, close nothing. An unmounted filesystem is indistinguishable from mass deletion, and one of those two readings eats your whole session. 31 unit tests + 2 fuzz properties, 10178 assertions, green.
Diffstat (limited to 'cli/src/core/purpose.ts')
-rw-r--r--cli/src/core/purpose.ts94
1 files changed, 94 insertions, 0 deletions
diff --git a/cli/src/core/purpose.ts b/cli/src/core/purpose.ts
new file mode 100644
index 0000000..728f27b
--- /dev/null
+++ b/cli/src/core/purpose.ts
@@ -0,0 +1,94 @@
+/**
+ * Tab identity.
+ *
+ * A project tab is keyed by its zellij tab `purpose`, because that is the only
+ * field the fork guarantees is (a) queryable via `list-tabs --json`, (b) not
+ * overridable in-band by whatever a pane is displaying, and (c) restored
+ * through the layout after a session is resurrected. Tab *names* are UI strings
+ * a human renames; they are not identity.
+ *
+ * The purpose carries the project's path RELATIVE TO THE ROOT, because
+ * `list-panes --json` exposes no `cwd` (verified against a live session), so
+ * there is no other way to get from a tab back to a directory on disk. Slashes
+ * survive the fork's sanitiser, so nested paths work.
+ *
+ * The fork's sanitiser: keep [A-Za-z0-9_.:/-], then truncate to 64 chars.
+ * See sanitize_pane_purpose() in zellij-utils/src/input/layout.rs.
+ */
+
+import { createHash } from "node:crypto";
+
+/** MAX_PANE_PURPOSE in the fork. */
+export const PURPOSE_MAX = 64;
+export const PROJECT_PREFIX = "project:";
+
+/** Everything the fork's sanitiser strips. */
+const DISALLOWED = /[^A-Za-z0-9_.:/-]/g;
+
+/** Reproduces sanitize_pane_purpose(): filter, then truncate. */
+export function sanitizePurpose(raw: string): string {
+ return raw.replace(DISALLOWED, "").slice(0, PURPOSE_MAX);
+}
+
+function hash8(value: string): string {
+ return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+
+/**
+ * Marks a purpose whose path was lossy and must never be reconstructed.
+ *
+ * A leading dot is safe as a sentinel because discovery skips dot-entries, so
+ * no real relative path we encode can begin with one.
+ *
+ * This has to be *structural*. The first implementation just re-encoded the
+ * candidate and compared, which silently failed: `project:<47 a's>.<hash8>` is
+ * itself 64 chars of legal characters, so it re-encodes to itself, the check
+ * passed, and a bogus path was "reconstructed" — which would have closed a
+ * live tab. Caught by `refuses to reconstruct a truncated/hashed purpose`.
+ */
+const LOSSY_MARK = ".";
+
+/**
+ * The purpose for a project at `relPath` (relative to its root).
+ *
+ * Normally this is simply `project:<relPath>`, which round-trips back to a
+ * path. When the path would not survive sanitising or does not fit, we fall
+ * back to a marked, truncated form plus a hash: still *unique*, deliberately
+ * not *reconstructable*, so `projectRelPath()` refuses it and we never
+ * auto-close a tab we cannot verify.
+ */
+export function projectPurpose(relPath: string): string {
+ const cleaned = sanitizePurpose(relPath);
+ const exact =
+ cleaned === relPath &&
+ cleaned.length > 0 &&
+ !cleaned.startsWith(LOSSY_MARK) &&
+ PROJECT_PREFIX.length + cleaned.length <= PURPOSE_MAX;
+ if (exact) return PROJECT_PREFIX + cleaned;
+
+ // sentinel(1) + head + "."(1) + hash8(8)
+ const budget = PURPOSE_MAX - PROJECT_PREFIX.length - 10;
+ const head = cleaned.slice(0, budget).replace(/[./-]+$/, "") || "project";
+ return `${PROJECT_PREFIX}${LOSSY_MARK}${head}.${hash8(relPath)}`;
+}
+
+export function isProjectPurpose(purpose: string | undefined | null): boolean {
+ return typeof purpose === "string" && purpose.startsWith(PROJECT_PREFIX);
+}
+
+/**
+ * The relative path a purpose encodes, or null when it cannot be reconstructed
+ * exactly.
+ *
+ * Null is not a failure, it is a refusal. A lossy purpose is marked at encode
+ * time and rejected here, so callers cannot mistake `project:.head.a1b2c3d4`
+ * for a directory literally named `head.a1b2c3d4` and close a tab over it. The
+ * re-encode comparison stays as a second line of defence.
+ */
+export function projectRelPath(purpose: string): string | null {
+ if (!isProjectPurpose(purpose)) return null;
+ const candidate = purpose.slice(PROJECT_PREFIX.length);
+ if (candidate.length === 0) return null;
+ if (candidate.startsWith(LOSSY_MARK)) return null;
+ return projectPurpose(candidate) === purpose ? candidate : null;
+}