@popoverinstall/cli 0.8.0 → 0.9.0

package/dist/vaults.d.ts

@@ -0,0 +1,276 @@
+import { type SnapshotEnvelope, type TranscriptEntry, type VaultSummary } from "@popoverinstall/shared";
+/**
+ * `popover vault` — a conversation frozen for the team, and asked later.
+ *
+ * The design is docs/vaults.md; this file is the terminal half of it. What matters when
+ * reading it is which of the three "copy of a conversation" things it is:
+ *
+ *   - `popover fork` hands one conversation to one named person, keyed by a code the server
+ *     never sees, and they carry it on as their own live session. It expires in 24 hours.
+ *   - a vault is published to a *team*, never expires, and is never carried on. It is only
+ *     ever asked, and the answer comes back attributed rather than as fact.
+ *
+ * Three consequences run through everything below.
+ *
+ * **The agent authors the description.** `--title` and `--answers` are written by the model,
+ * not prompted for, because the one moment anybody knows what a conversation is authoritative
+ * about is while they are still inside it (docs/vaults.md §3). So `create` validates the
+ * description properly and refuses a bad one with a sentence a model can act on, rather than
+ * relaying a constraint violation from Postgres.
+ *
+ * **Looking is free and asking is not.** `list` is stage one — a string comparison, no model
+ * call — and `ask` is stage two, which resumes a whole conversation and bills for it at
+ * roughly the cold-ask numbers in `fork.ts` ($0.46, 97s). They are separate verbs and
+ * separate IPC arms precisely so that an agent that cannot do the first without the second
+ * does not end up doing the second by default (§6).
+ *
+ * **A vault is readable by the service, and `popover fork` is not.** Anyone who has
+ * internalized the fork's promise will assume this one makes it too. §1 requires the publish
+ * confirmation to say otherwise out loud, so `create` prints it every time and reports
+ * `readable_by_service` in its JSON.
+ *
+ * There is deliberately no edit verb. A vault is archived, never rewritten; a correction is a
+ * `note`, which sits beside the original rather than replacing it (§2, §5). What a vault
+ * originally claimed is evidence about what the team believed at the time.
+ */
+export declare function vaultCommand(rest: string[]): Promise<number>;
+/** Everything that is not a flag and not a flag's value, in the order it was typed. */
+export declare function positionals(args: string[]): string[];
+/** Every occurrence of a repeatable flag. `--answers` is the only one, and it is the point. */
+export declare function flagAll(args: string[], name: string): string[];
+export type AnswersResult = {
+    ok: true;
+    answers: string[];
+} | {
+    ok: false;
+    message: string;
+    hints: string[];
+};
+/**
+ * Read `--answers`, which an agent may pass either repeatably or as one JSON array.
+ *
+ * Both forms exist because both are natural to generate: a shell-shaped caller repeats the
+ * flag, and a model writing a single argument writes JSON. What must not happen is the third
+ * outcome — a JSON array that fails to parse being stored verbatim as one long question, which
+ * would upload a vault whose entire retrieval surface is the string `["why did we...`. So
+ * anything that opens with `[` is committed to being JSON, and is refused rather than
+ * salvaged if it is not.
+ */
+export declare function parseAnswers(raw: string[]): AnswersResult;
+export interface VaultPlanInput {
+    name?: string | undefined;
+    title?: string | undefined;
+    answers: string[];
+}
+export type VaultPlan = {
+    ok: true;
+    name: string;
+    title: string;
+    answers: string[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    hints: string[];
+};
+/**
+ * Decide what this vault is called and whether it is describable at all, before anything is
+ * read off the network.
+ *
+ * The name is checked here rather than left to the server for two reasons. The unique index
+ * is on `lower(name)`, so `normalizeVaultName` can produce the same collision locally and say
+ * something better than a constraint violation; and a name that normalizes to nothing —
+ * a title of "???" — would otherwise reach the route as an empty string and come back as a
+ * 400 that reads like a bug in popover rather than a title worth rewriting.
+ *
+ * `answers` is the one that matters most and is the one an agent is most likely to skip.
+ * It holds *questions this conversation can answer*, not a summary, because the incoming
+ * query at retrieval time is a question and matching question against summary retrieves
+ * badly (§6). Refusing an empty list is the only moment anybody is in a position to enforce
+ * that.
+ */
+export declare function planVault(input: VaultPlanInput): VaultPlan;
+export type VaultMatch = {
+    kind: "one";
+    vault: VaultSummary;
+} | {
+    kind: "none";
+} | {
+    kind: "many";
+    matches: VaultSummary[];
+};
+/**
+ * Which vault a typed reference means: by id, then exact name, then unique prefix.
+ *
+ * Every match is returned rather than the first, and the same widening `resolveTeam` does is
+ * used, for the same reason: two names sharing a prefix is a real arrangement, and asking the
+ * wrong vault costs a dollar and produces a confident answer about the wrong subsystem, which
+ * is the failure nobody notices.
+ */
+export declare function resolveVaultRef(vaults: VaultSummary[], typed: string): VaultMatch;
+/**
+ * Whether a reference is already an id, so no lookup is needed to use it.
+ *
+ * The full UUID shape rather than "has hyphens", because vault names have hyphens in them by
+ * construction — `repo-key-gating` is the example the spec itself uses. Treating one as an id
+ * would POST a note to `/api/vaults/repo-key-gating/notes` and report the 404 as a missing
+ * vault, when the vault is right there under a name we simply never resolved.
+ */
+export declare function looksLikeVaultId(ref: string): boolean;
+/**
+ * The freeze date, in the form §4 writes it: `15 Aug 2026`.
+ *
+ * The locale is pinned rather than left to the machine because this string is part of an
+ * attribution that gets pasted into other conversations and read by other models, so
+ * `8/15/2026` on one laptop and `15/08/2026` on the next is an ambiguity with no upside.
+ */
+export declare function freezeDate(iso: string): string;
+/**
+ * The sentence a vault's answer is always wrapped in.
+ *
+ * Never optional, and never assembled by the caller. A human reading an answer supplies the
+ * skepticism unprompted; an agent will not unless the format forces it, and a vault can hold
+ * a hypothesis the team later disproved. So the title and the freeze date travel on
+ * `VaultAnswer` itself and this turns them into the one line that must precede the answer —
+ * including in `--json`, where the assembled string is a field rather than a suggestion.
+ */
+export declare function attribution(answer: {
+    title: string;
+    frozenAt: string;
+    gitSha?: string | undefined;
+}): string;
+/**
+ * How a staleness score reads to a person.
+ *
+ * Words rather than the number, because the number is a ratio of paths and nobody ranks
+ * vaults by reading ratios. A vault that recorded no paths at all scores 0 the same way an
+ * untouched one does — `stalenessScore` deliberately does not punish absent evidence — so
+ * "nothing it touched has changed" is only claimed when the server sent a score at all.
+ */
+export declare function stalenessNote(staleness: number | undefined): string;
+/** One vault as a person reads it in a list: a heading, a byline, and its questions. */
+export declare function summaryLines(v: VaultSummary): string[];
+/**
+ * One vault as a script reads it.
+ *
+ * Absent values are `null` rather than missing, because the consumer is usually a model
+ * deciding whether to spend a dollar on stage two, and a key that is sometimes there reads as
+ * a key it forgot to look at.
+ */
+export declare function summaryJson(v: VaultSummary): Record<string, unknown>;
+/**
+ * Read a listing from the HTTP route, accepting either spelling of its fields.
+ *
+ * The IPC path parses `VaultSummarySchema` and gets camelCase by construction. The HTTP route
+ * is written in another package against §10, which names those same columns `author_label`,
+ * `created_at` and `note_count` — so both spellings are plausible and neither is worth a
+ * cross-package coordination round to settle. Accepting both here costs a few lines and means
+ * `note` and `archive` cannot be broken by a naming choice made in `apps/web`.
+ *
+ * Returns null for a body that is not a listing at all, which is what an SSO proxy or a
+ * protected preview answers with — see `ApiFailure.malformed`.
+ */
+export declare function readSummaries(body: unknown): VaultSummary[] | null;
+/**
+ * Keep `--limit` inside what the daemon's schema will accept.
+ *
+ * Clamped rather than relayed, because `VaultSearchRequestSchema` caps it at 50 and floors it
+ * at 1, and a rejected request comes back as a generic `bad_request` from the daemon that
+ * says nothing about the number somebody typed.
+ */
+export declare function clampLimit(raw: string | undefined, fallback?: number): number;
+/** Same clamp, for `--timeout`, whose schema window is 5 to 600 seconds. */
+export declare function clampTimeout(raw: string | undefined, fallback?: number): number;
+/**
+ * The files this conversation read or wrote, from the transcript itself.
+ *
+ * This is the primary source for `touched_paths`, and the working tree is the secondary one,
+ * which is the opposite of how it first looked. `touched_paths` exists to answer "does this
+ * conversation's reasoning depend on files that have since changed", and `git status` answers
+ * a narrower question: what was uncommitted at the moment somebody vaulted. Two ordinary
+ * cases fall through that gap — a conversation that committed its work before vaulting, and a
+ * read-only conversation that changed nothing — and both land on an empty list.
+ *
+ * Empty is not neutral. `stalenessScore` deliberately returns 0 for a vault that recorded no
+ * paths, on the correct reasoning that absence of evidence is not churn; so a vault with an
+ * empty list ranks as permanently current and never decays. The two behaviours are each right
+ * and together wrong, and the read-heavy vaults they hit hardest are the valuable ones.
+ *
+ * Paths that do not fall under any of `roots` are dropped rather than stored absolute. They
+ * could never match a path from `git status`, so keeping them would only pad the denominator
+ * of `hits / touchedPaths.length` and make every vault look more current than it is.
+ */
+export declare function collectToolPaths(entries: TranscriptEntry[], roots: readonly string[], cap?: number): string[];
+/**
+ * The two sources, deduped and capped once.
+ *
+ * The transcript comes first so that it survives truncation: if a conversation named more
+ * than the cap on its own, what it read and wrote is a better description of what it depended
+ * on than whatever happened to be dirty in the tree at the time.
+ */
+export declare function unionPaths(primary: string[], secondary: string[], cap?: number): string[];
+/**
+ * The uncommitted half, from `git status --porcelain`.
+ *
+ * Unioned with `collectToolPaths` rather than replaced by it, because work that a conversation
+ * left dirty is genuine evidence about what it touched — it is only insufficient on its own.
+ *
+ * Renames are recorded at their destination: `R  old -> new` is churn in `new`, and ranking a
+ * vault against a path that no longer exists would make every renamed file look permanently
+ * untouched. Quoted paths are unescaped because `core.quotePath` is on by default and a
+ * filename with an accent in it would otherwise be stored complete with its surrounding
+ * quotes and never match anything.
+ *
+ * The cap is `VaultIndexSchema`'s 500. A conversation that dirtied more than that is a
+ * generated-file situation where the first 500 are as good a signal as any.
+ */
+export declare function parseTouchedPaths(porcelain: string, cap?: number): string[];
+/**
+ * A commit sha, or nothing.
+ *
+ * `git rev-parse HEAD` in a repository with no commits prints the literal string `HEAD` and
+ * exits nonzero on some versions and zero on others. `VaultIndexSchema.gitSha` is a hex regex,
+ * so letting that through turns a first-commit-pending repo into a 400 from the create route
+ * that reads as a popover bug rather than as "there is no commit yet".
+ */
+export declare function cleanSha(raw: string | undefined): string | undefined;
+/**
+ * The transcript, compressed, as one opaque string.
+ *
+ * Deliberately **not** `sealSnapshot`. That derives its AES key from the fork code, and a
+ * vault has no code — team membership is the whole credential, which is exactly the decision
+ * §1 records and the reason the server can read a vault at all. Encrypting here with a key
+ * stored beside the ciphertext would be worse than not encrypting: a promise that reads as
+ * strong and is not. The real protection is at-rest encryption under a key held outside the
+ * database, which is the server's to do.
+ *
+ * gzip + base64 anyway, because `body` is one opaque column by design (§2) so a later
+ * end-to-end version can wrap a per-vault key around this without moving anything else, and
+ * because a transcript compresses about 10:1.
+ */
+export declare function packBody(envelope: SnapshotEnvelope): string;
+export interface ApiFailure {
+    ok: false;
+    status: number;
+    /** The `error` code from any of our own error bodies. */
+    error?: string;
+    /** A sentence the server wrote, when it sent one. Relayed rather than rewritten. */
+    message?: string;
+    /**
+     * Something answered with a success status and a body that is not what this route returns.
+     * Its own flag rather than a status, because the status is 200 and "failed (200)" is not a
+     * sentence anybody can act on. In practice it is an auth wall that redirects rather than
+     * refusing, and `fetch` follows the redirect.
+     */
+    malformed?: true;
+    /**
+     * Whether our API refused this, or something in front of it did.
+     *
+     * A 401 from the route means the device token is no longer good and the fix is
+     * `popover login`; a 401 from an SSO proxy or a protected preview means nothing of the sort,
+     * and sending somebody to re-authenticate over it wastes their time on the wrong problem.
+     * Our routes always answer with a JSON `error` string; a wall answers with something else.
+     */
+    ours: boolean;
+}
+//# sourceMappingURL=vaults.d.ts.map

package/dist/vaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vaults.d.ts","sourceRoot":"","sources":["../src/vaults.ts"],"names":[],"mappings":"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"}