wingfoil 0.2.1 → 0.3.0

package/dist/memory/add.d.ts

@@ -1,8 +1,12 @@
 /**
  * Turn a human `--title` into a single, valid `[a-z0-9-.]` ID slug piece (spec-009-validation-strategy
  * §1's ID character class, the same one `generateId` enforces): lowercase, every run of characters
- * outside `[a-z0-9]` collapsed to one `-`, and no leading/trailing/doubled `-`. Deterministic and
- * idempotent-shaped so `generateId`'s Pass-B slug check (`[a-z0-9.]+(?:-[a-z0-9.]+)*`) accepts it.
+ * outside `[a-z0-9]` collapsed to one `-`, and no leading/trailing/doubled `-` — except that a run
+ * consisting of exactly one `.` between two alphanumerics is **kept** (`v0.2` → `v0.2`,
+ * `dl-107` S1 (a), task-110). That is the character rule `generateId`'s Pass-B slug check
+ * (`[a-z0-9.]+(?:-[a-z0-9.]+)*`) already accepts, so the slugifier and the validator share one rule
+ * instead of the slug being stricter than the id it feeds. Ids added before this rule are untouched:
+ * an id is immutable once added.
  */
 export declare function slugifyTitle(title: string): string;
 /**
@@ -11,40 +15,179 @@ export declare function slugifyTitle(title: string): string;
  * default rather than writing an empty list).
  */
 export declare function parseTags(raw: string | undefined): string[] | undefined;
-/** Whether an `id_pattern` contains a `{n}`-family numeric token (e.g. `task-{n}-{slug}`) — i.e. it
- * needs a sequence counter resolved before {@link generateId} can render it. */
+/** Whether an `id_pattern` contains a `{n}`-family numeric token (e.g. `task-{n}-{slug}`, `u-{n:1}`) —
+ * i.e. it needs a sequence counter resolved before {@link generateId} can render it. */
 export declare function hasNumericToken(idPattern: string): boolean;
 /**
- * The directory that holds every document of a type: the type's `path` pattern
- * (spec-001-memory-yaml-schema `MemoryTypeEntry.path`, e.g. `docs/memory/decision/{id}.md`) rendered
- * with a dummy `{id}` and reduced to its containing directory. The directory portion never depends on
- * the concrete id value, so this is well-defined before the id is generated (used by
- * {@link nextSequenceNumber} to count existing siblings).
+ * The author date git would record for a commit made now at `root`, as git's internal
+ * `<seconds> <offset>` pair (`1790731800 -0200`): `GIT_AUTHOR_DATE` when it is set, in any format git
+ * accepts, otherwise the system clock — read ONCE, through `git var GIT_AUTHOR_IDENT` (task-163,
+ * `bug-158`). `memory add` builds `{date}` from it ({@link formatIdDate}) and records the add commit
+ * with this same author date (passed back as `@<seconds> <offset>`: git reads a bare pair as a
+ * timestamp only from 9 digits of seconds up), so the id and the commit cannot disagree, and a caller (a test, a
+ * replay) fixes the date the way it fixes any git author date.
+ *
+ * `identity` is passed to git as `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL`: the identity was already
+ * resolved and checked (`requireGitIdentity`), and only the date part of git's answer is read.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when git refuses (e.g. a `GIT_AUTHOR_DATE` it
+ *   cannot parse) or answers in a shape that is not `… <seconds> <offset>`.
+ */
+export declare function readAuthorDate(root: string, identity: {
+    readonly name: string;
+    readonly email: string;
+}): string;
+/**
+ * The `<seconds> <offset>` date that ends a git ident line (`Name <email> 1790731800 -0200`). Pure.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when the line does not end with one.
+ */
+export declare function identDate(ident: string): string;
+/**
+ * `{date}`'s value (`spec-001`'s placeholder table): the UTC calendar date `YYYYMMDD` of a git
+ * `<seconds> <offset>` date ({@link readAuthorDate}). The offset does not move the instant, so
+ * `23:30 -0200` on the 29th is the 30th. Pure.
+ */
+export declare function formatIdDate(gitDate: string): string;
+/**
+ * The highest `{n}` value among `paths` (repository-relative, `/`-separated) that the type's `path`
+ * pattern and materialized `id_pattern` match, or `0` when none does (`spec-001` "Counter algorithm",
+ * `dl-101` §2 (a)). The **highest**, not a count, so a gap never reissues a number (`bug-087`); and a
+ * maximum, so the answer is independent of the order `paths` arrive in (REQ-SYS-07).
+ */
+export declare function highestSequenceNumber(paths: Iterable<string>, pathPattern: string, idPattern: string): number;
+/**
+ * The commits of the refs a number or a WIP slot can be taken on (`dl-101` §2 (a)): the tip of every
+ * local branch (`refs/heads/*`) and remote-tracking ref (`refs/remotes/*`), and `HEAD` (a detached
+ * `HEAD` is on no branch; an unborn one adds nothing), as full shas, de-duplicated and sorted
+ * (REQ-SYS-07). No network: the remote-tracking refs are what the last `git fetch` left (`dl-101`
+ * §1.1).
+ *
+ * The one listing of "every ref" both wider reads use — `memory add`'s `{n}` counter
+ * ({@link nextSequenceNumber}) and the WIP-limit holder count (`requireWipSlot`, `dl-156` Q1 (a),
+ * task-274) — so the two cannot disagree about which refs exist (`command-baseline`, *Declared
+ * baselines*).
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
  */
-export declare function resolveTypeDirectory(root: string, pathPattern: string): string;
+export declare function refBaselineCommits(root: string): string[];
 /**
- * The next sequence number for a `{n}`-token id: `1 +` the count of existing files in `dir` whose
- * basename (sans `.md`) matches `idPattern` (`patternToRegExp`, task-002). Deterministic — a count is
- * independent of directory-entry order (REQ-SYS-07) — and confined to this type's own directory, so
- * unrelated files never perturb it. Returns `1` when the directory does not yet exist.
+ * The next sequence number for a `{n}`-token id: `1 +` the highest number any baseline holds for this
+ * type — every local branch, remote-tracking ref, `HEAD`, the index and the untracked working-tree
+ * files ({@link sequenceCandidatePaths}) — over every folder the type's `path` can resolve to
+ * ({@link highestSequenceNumber}). `1` when nothing matches. Ratified `dl-101` §2 (a) (task-128,
+ * `bug-087`, `bug-162`); `spec-001` "Counter algorithm".
+ *
+ * @param root - The repository root.
+ * @param pathPattern - The type's committed `path` pattern, e.g. `docs/04_memory/{release}/{id}.md`.
+ * @param idPattern - The type's `id_pattern` with its field tokens already materialized.
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
  */
-export declare function nextSequenceNumber(dir: string, idPattern: string): number;
-/** The fields `memory.add` pins on the freshly-created draft document (P1.3 memory.add / spec-010). */
+export declare function nextSequenceNumber(root: string, pathPattern: string, idPattern: string): number;
+/**
+ * Which ids of a type with `path` pattern `pathPattern` exist on any baseline a number can be taken on —
+ * the ones {@link nextSequenceNumber} reads (every local branch, remote-tracking ref, `HEAD`, the index and
+ * the untracked working-tree files; `dl-101` §2 (a)) — in any folder the pattern resolves to: every token
+ * other than `{id}` matches one or more path segments. The paths are listed once; the returned predicate
+ * answers for any id. `workflow start` asks it of a derived or `--set phase=` plan id (`spec-017` §7.1,
+ * task-217): ids are unique per type, so a plan held by another branch, or under another `{scope}`,
+ * occupies its id.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
+ */
+export declare function idOccupancy(root: string, pathPattern: string): (id: string) => boolean;
+/** The fields `memory.add` pins on the freshly-created document (P1.3 memory.add / spec-010). */
 export interface AddDocumentFields {
     readonly id: string;
     readonly title: string;
     readonly tags?: readonly string[];
+    /**
+     * Frontmatter fields `memory add --set` fills (task-110, `dl-107` S2 (a)), as `[name, value]` pairs
+     * in the order they are written — {@link writtenFields} produces them sorted by name
+     * (REQ-SYS-07). Each is written as a JSON-quoted string, replacing the scaffold's line for that key
+     * or appended when the scaffold has none.
+     */
+    readonly fields?: readonly (readonly [string, string])[];
+    /**
+     * The initial `status`: the head of the type's machine (`spec-001`; `bug-214`, task-180), which
+     * `memory add` resolves from the committed `memory.yaml`. Defaults to `draft`, the head of the
+     * built-in default machine.
+     */
+    readonly status?: string;
 }
 /**
  * Copy a type's `template.file` scaffold verbatim and fill only the frontmatter skeleton `memory.add`
  * pins (P1.3; spec-010-memory-frontmatter-schema): the generated `id`, the `--title`, the
- * initial `status: draft`, and — when `--tags` was supplied — the `tags` flow sequence. Every other
+ * initial `status` (the head of the type's machine, {@link AddDocumentFields.status}), when `--tags`
+ * was supplied the `tags` flow sequence, and the `--set` fields
+ * {@link AddDocumentFields.fields} carries (task-110). Every other
  * field (notably `type` and `tmpl_version`, spec-010: not touched by add) and the whole body are left
  * exactly as the scaffold had them. `title`/`tags` are JSON-quoted (valid YAML double-quoted scalars /
  * flow sequences), so an arbitrary title with spaces or colons is written safely.
  *
+ * Each field is set through `./frontmatter-edit`'s shared setter, the one the transition verbs use
+ * (task-163, `bug-033`): only a TOP-LEVEL key is matched, so a nested key of the same name is never
+ * edited, and an edited line keeps the scaffold's inline `# comment`.
+ *
  * @throws when the scaffold has no frontmatter block (a malformed template — a config error surfaced
  *   as a thrown `Error` the core op maps to a `CoreError`).
  */
 export declare function renderAddDocument(scaffold: string, fields: AddDocumentFields): string;
+/** The outcome of {@link parseSetOptions}: the parsed values, or the one usage-error message. */
+export type ParsedSetOptions = {
+    readonly ok: true;
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Parse `memory add`'s repeatable `--set <name>=<value>` occurrences (`spec-008-cli-grammar` §10,
+ * task-110). The CLI hands every occurrence as a string array; a single string is one occurrence;
+ * `undefined` is none. `<name>` is split from `<value>` at the FIRST `=`.
+ *
+ * Every refusal here is a property of how the argument is spelled, decided before anything is read,
+ * so the caller raises it as a usage error (exit 2) — the first failing occurrence, in the order
+ * given, with §10's exact message. Pure and order-preserving (REQ-SYS-07).
+ */
+export declare function parseSetOptions(raw: string | readonly string[] | undefined): ParsedSetOptions;
+/**
+ * The `--set` names a type's committed patterns cannot use: every name that is not a token of its
+ * `id_pattern` or of its `path` (other than `{id}`), in the order given. `memory add` refuses them
+ * (exit 1, `spec-008` §10) rather than writing a field no token reads.
+ */
+export declare function unknownSetNames(values: Readonly<Record<string, string>>, idPattern: string, pathPattern: string): string[];
+/**
+ * The values of the tokens `memory add` sources itself rather than from `--set` (`spec-001`'s
+ * placeholder table, task-163): `{date}` and `{author}`. Each is needed only when the pattern has the
+ * token, and is read once per add by the caller.
+ */
+export interface IdTokenSources {
+    /** The add commit's author date as git's `<seconds> <offset>` ({@link readAuthorDate}). */
+    readonly date?: string;
+    /** The git author name the add commit records (`requireGitIdentity`), before slugging. */
+    readonly authorName?: string;
+}
+/**
+ * Materialize an `id_pattern`'s `{date}`, `{author}`, frontmatter and context tokens (`{kind}`,
+ * `{version}`, `{workflow}`, …), leaving `{slug}` and the `{n}` family in place — `spec-001`'s fixed
+ * expansion order (`{date}` → `{author}` → field and context tokens → `{slug}` → `{n}`), so the
+ * `{n}` counter regexp built from the result sees a fully-materialized prefix (task-110). `{date}` is
+ * the UTC `YYYYMMDD` of `sources.date` ({@link formatIdDate}); `{author}` the slug of
+ * `sources.authorName` ({@link slugifyTitle}) — task-163, `bug-158`.
+ *
+ * @throws {@link ValidationError} naming every field token with no value
+ *   (`missing value for token {<name>}: give it with --set <name>=<value>`), an `{author}` whose
+ *   name slugs to nothing, and every value outside the ID character class, in pattern order — the
+ *   same `E_INVALID_ID` code `generateId` raises.
+ */
+export declare function expandFieldTokens(idPattern: string, values: Readonly<Record<string, string>>, sources?: IdTokenSources): string;
+/**
+ * The `--set` values `memory add` writes into the new document's frontmatter, as `[name, value]`
+ * pairs sorted by name (REQ-SYS-07). A field token is always written, so the id and the field cannot
+ * disagree (`dl-107` S2 (a)); a context token (`workflow`, `phase`, `scope`) only where the committed
+ * scaffold's frontmatter declares that key (`dl-107` S2 (c) — `plan` declares `workflow` and `phase`,
+ * not `scope`).
+ */
+export declare function writtenFields(scaffold: string, values: Readonly<Record<string, string>>): [string, string][];
 //# sourceMappingURL=add.d.ts.map

package/dist/memory/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/memory/add.ts"],"names":[],"mappings":"AAmBA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAOvE;AAED;gFACgF;AAChF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAK1D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQzE;AAED,uGAAuG;AACvG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAcrF"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/memory/add.ts"],"names":[],"mappings":"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"}