@starci/seed 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.0 - 2026-11-17
4
+
5
+ - Added (`@starci/seed/git`): the adapter of a seed-standard that keeps its authored material in `raw/` (PROJECT-STACKS-13, R434). `renderStandard(content, outDir)` writes `{format, project, entries}` through `createGitDriver` into a scratch working copy (plaintext, purpose seed-standard) and replaces `manifest.json`, `data/`, `blobs/` and `index/` of `outDir`, leaving every other file; `takenAt` is `STANDARD_TAKEN_AT` (1970-01-01T00:00:00.000Z) and `source.environment` is `STANDARD_ENVIRONMENT` (standard), so the same content renders the same bytes in any entry order; a format that is no `<name>-seed-standard@<major>` is refused `DATA_FORM_REFUSED`. `runStandardAdapter(convert, argv)` is the body of an adapter's `main.ts`: `--raw` (default raw) and `--out` (default the repository root), exit 0, usage 2, a failed convert or render 1 with its code or error on one line. Types `StandardContent`, `StandardConvert`, `RenderOptions`, `AdapterIo`; constants `STANDARD_OUTPUTS`, `STANDARD_RAW`.
6
+
3
7
  ## 0.1.0 - 2026-11-14
4
8
 
5
9
  The ports of the data standard (PROJECT-STACKS-13, PROJECT-STACKS-14) in one package: what must be kept, where a copy is kept, and one export written to several copies. It was first written under `@starci/common/data` and moves here before any release, so `@starci/common` stays at 1.0.1.
package/README.md CHANGED
@@ -15,12 +15,16 @@ The law is [contexts/project/stacks.md](../../contexts/project/stacks.md), PROJE
15
15
  | `@starci/seed` | the ports and the copy contract: `StoreAdapter` (a thing that must be kept: a database or a storage bucket; describes its sets, exports entries in (set, key) byte order, imports them by natural key keeping each row's identity, `merge` or `mirror`, dry run, `identityOf`), `DriverAdapter` (where a copy is kept: git now, s3 later; plans, writes, lists, reads, verifies, refuses with the coded `DataRefusal`), `DataManifest` with `ManifestBuilder`, `exportOnce`, `writeEverywhere` (each driver an isolated leg), `compareCopies`, `chooseCopy`, `restoreFrom`, and the line protocol `starci/data-entries@1` (`serveStore`, `commandStore`) that carries a store through an app's own command |
16
16
  | `@starci/seed/testing` | `memoryStore`, `memoryDriver` (with failure and corruption switches), `memorySpool`, and the contract suites `storeContract` and `driverContract`: a real adapter runs them against its fakes (each case throws when a promise is broken, in any test runner) |
17
17
  | `@starci/seed/postgres` | `postgresStore` (the whole relational database as deterministic per-table rows behind `StoreAdapter`; the app hands a `PostgresRunner` and no SQL), see below |
18
- | `@starci/seed/git` | `createGitDriver` (the `git` driver over a local working copy), `pinRepository` (a copy repository at one pinned commit, read in place) and `openReviewTree` (writes and seals into a tree a person reviews), for a kind a project defines on top of the standard |
18
+ | `@starci/seed/git` | `createGitDriver` (the `git` driver over a local working copy), `pinRepository` (a copy repository at one pinned commit, read in place) and `openReviewTree` (writes and seals into a tree a person reviews), for a kind a project defines on top of the standard; `renderStandard` and `runStandardAdapter`, the adapter of a standard that keeps its authored material in `raw/` (below) |
19
19
 
20
20
  ## The git driver's layout
21
21
 
22
22
  `manifest.json` (schema `starci/data-manifest@1`: the sets with counts and digests, the file index, the shard widths, the sealing and its public recipients; no value), record shards `data/<store>/<set>/<shard>.json` (hash-prefix shards, the width only grows), object chunks `blobs/<store>/<set>/<aa>/<id>[.<n>].bin` and `index/<store>/<set>.json`. `.gitattributes` holds `* -text` so line endings never touch a file. A file whose plaintext did not change is never rewritten, and an unchanged export commits nothing.
23
23
 
24
+ ## The adapter of a standard
25
+
26
+ A standard whose content is awkward as JSON records keeps what people author in `raw/` and an `adapter/` (PROJECT-STACKS-13, R434). `adapter/convert.ts` exports `convert(rawDir)`, answering `{format, project, entries}` (each entry `{store, entry}` from `recordEntry` or `blobEntry`); `adapter/main.ts` is `process.exitCode = await runStandardAdapter(convert, process.argv.slice(2))`. `renderStandard` writes the entries through `createGitDriver` into a scratch working copy and replaces `manifest.json`, `data/`, `blobs/` and `index/` of the output folder, nothing else. Its output is deterministic: sets and keys sorted, canonical JSON, `takenAt` fixed at `STANDARD_TAKEN_AT` and `source.environment` at `STANDARD_ENVIRONMENT`; the adapter brings no clock or random id. The copy repository's hook and CI re-run it and refuse a committed output that differs (`HFS_DATA_ADAPTER_DRIFT`); `starci data standard init --adapter` scaffolds it.
27
+
24
28
  ## Sealing by purpose
25
29
 
26
30
  The purpose decides: a `seed-standard` is plaintext (readable for review), a `seed-backup` is sealed with sops in binary mode to the age recipients of its environment, every file as `*.sops.json`. `verify` checks the manifest, the sealing policy, stray, missing and unsealed files, envelopes, the cap and, with an identity (or for a plaintext copy), every digest.
@@ -2,3 +2,5 @@ export { createGitDriver } from "./driver.js";
2
2
  export type { GitDriverOptions, RunResult, Runner } from "./driver.js";
3
3
  export { openReviewTree, pinRepository } from "./files.js";
4
4
  export type { PinOptions, PinnedRepository, ReviewTree } from "./files.js";
5
+ export { STANDARD_ENVIRONMENT, STANDARD_OUTPUTS, STANDARD_RAW, STANDARD_TAKEN_AT, renderStandard, runStandardAdapter } from "./standard.js";
6
+ export type { AdapterIo, RenderOptions, StandardContent, StandardConvert } from "./standard.js";
package/dist/git/index.js CHANGED
@@ -1,2 +1,3 @@
1
1
  export { createGitDriver } from "./driver.js";
2
2
  export { openReviewTree, pinRepository } from "./files.js";
3
+ export { STANDARD_ENVIRONMENT, STANDARD_OUTPUTS, STANDARD_RAW, STANDARD_TAKEN_AT, renderStandard, runStandardAdapter } from "./standard.js";
@@ -0,0 +1,60 @@
1
+ import type { StoredEntry } from "../copies.js";
2
+ import type { Runner } from "./driver.js";
3
+ /**
4
+ * The adapter of a seed-standard repository (PROJECT-STACKS-13): a standard whose content is awkward to author as JSON
5
+ * records keeps what people write in `raw/` and an `adapter/` whose `convert(rawDir)` turns it into entries; this file
6
+ * writes those entries through the one git driver into the standard layout (`manifest.json`, `data/`, `blobs/`,
7
+ * `index/`), so an adapter never writes a copy file itself.
8
+ *
9
+ * Determinism is the contract the commit hook proves (R434, HFS_DATA_ADAPTER_DRIFT): the same `raw/` yields the same
10
+ * bytes. The driver already sorts sets and keys and writes canonical JSON; this file fixes the rest: `takenAt` is
11
+ * STANDARD_TAKEN_AT (a standard is identified by its commit, never by a time) and `source.environment` is
12
+ * STANDARD_ENVIRONMENT. What is left to the adapter is its content: no clock, no random id, no order the file system
13
+ * chose.
14
+ */
15
+ /** The `takenAt` of every standard an adapter renders: fixed, so the manifest is a function of `raw/` alone. */
16
+ export declare const STANDARD_TAKEN_AT = "1970-01-01T00:00:00.000Z";
17
+ /** The `source.environment` of a rendered standard: it belongs to every environment that loads it, so it names none. */
18
+ export declare const STANDARD_ENVIRONMENT = "standard";
19
+ /** What an adapter run writes at the root of the standard, and all it may write: the rest of the repository is people's. */
20
+ export declare const STANDARD_OUTPUTS: readonly string[];
21
+ /** The folder people author in, kept plain; never written by an adapter. */
22
+ export declare const STANDARD_RAW = "raw";
23
+ /** What `convert` answers: the standard's format (`<name>-seed-standard@<major>`), its project and every entry with its store. */
24
+ export interface StandardContent {
25
+ /** `<repository name>@<major>`; the name ends `-seed-standard`. */
26
+ readonly format: string;
27
+ /** The project the standard seeds. */
28
+ readonly project: string;
29
+ /** Every entry, each with the store id it is loaded into (a store `data.stores` of the app declares). Any order. */
30
+ readonly entries: readonly StoredEntry[];
31
+ }
32
+ /** An adapter's one export: reads `rawDir` (the standard's `raw/`) and answers its content; it writes nothing. */
33
+ export type StandardConvert = (rawDir: string) => StandardContent | Promise<StandardContent>;
34
+ /** Seams of a render: the program runner of the git driver, and where its scratch working copy is made. */
35
+ export interface RenderOptions {
36
+ /** Runs git; spawnSync by default. */
37
+ readonly run?: Runner;
38
+ /** The parent of the scratch working copy; the system temp directory by default. */
39
+ readonly scratch?: string;
40
+ }
41
+ /**
42
+ * Writes `content` into `outDir` as a seed-standard: the entries go through `createGitDriver` into a scratch working copy
43
+ * (plaintext, the standard's purpose), and its `manifest.json`, `data/`, `blobs/` and `index/` replace those of `outDir`.
44
+ * A format that is no standard's is refused `DATA_FORM_REFUSED`; a repeated key or a set mixing forms is the manifest
45
+ * builder's TypeError.
46
+ */
47
+ export declare function renderStandard(content: StandardContent, outDir: string, options?: RenderOptions): Promise<void>;
48
+ /** Where an adapter run prints. */
49
+ export interface AdapterIo {
50
+ /** The directory `--raw` and `--out` resolve against; the process's by default. */
51
+ readonly cwd?: string;
52
+ /** Prints one line of the run; stderr by default. */
53
+ readonly print?: (line: string) => void;
54
+ }
55
+ /**
56
+ * The body of an adapter's `main.ts`: `process.exitCode = await runStandardAdapter(convert, process.argv.slice(2))`.
57
+ * Converts `--raw` (default `raw`) and renders the standard into `--out` (default `.`, the repository root): exit 0;
58
+ * a usage problem is 2, a failed convert or render 1, with the refusal's code or the error on one line.
59
+ */
60
+ export declare function runStandardAdapter(convert: StandardConvert, argv: readonly string[], io?: AdapterIo): Promise<number>;
@@ -0,0 +1,105 @@
1
+ import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
2
+ import { tmpdir } from "node:os";
3
+ import { join, resolve } from "node:path";
4
+ import { memorySpool, spooledSource } from "../copies.js";
5
+ import { DataRefusal } from "../driver.js";
6
+ import { ManifestBuilder } from "../manifest.js";
7
+ import { createGitDriver } from "./driver.js";
8
+ /**
9
+ * The adapter of a seed-standard repository (PROJECT-STACKS-13): a standard whose content is awkward to author as JSON
10
+ * records keeps what people write in `raw/` and an `adapter/` whose `convert(rawDir)` turns it into entries; this file
11
+ * writes those entries through the one git driver into the standard layout (`manifest.json`, `data/`, `blobs/`,
12
+ * `index/`), so an adapter never writes a copy file itself.
13
+ *
14
+ * Determinism is the contract the commit hook proves (R434, HFS_DATA_ADAPTER_DRIFT): the same `raw/` yields the same
15
+ * bytes. The driver already sorts sets and keys and writes canonical JSON; this file fixes the rest: `takenAt` is
16
+ * STANDARD_TAKEN_AT (a standard is identified by its commit, never by a time) and `source.environment` is
17
+ * STANDARD_ENVIRONMENT. What is left to the adapter is its content: no clock, no random id, no order the file system
18
+ * chose.
19
+ */
20
+ /** The `takenAt` of every standard an adapter renders: fixed, so the manifest is a function of `raw/` alone. */
21
+ export const STANDARD_TAKEN_AT = "1970-01-01T00:00:00.000Z";
22
+ /** The `source.environment` of a rendered standard: it belongs to every environment that loads it, so it names none. */
23
+ export const STANDARD_ENVIRONMENT = "standard";
24
+ /** What an adapter run writes at the root of the standard, and all it may write: the rest of the repository is people's. */
25
+ export const STANDARD_OUTPUTS = Object.freeze(["manifest.json", "data", "blobs", "index"]);
26
+ /** The folder people author in, kept plain; never written by an adapter. */
27
+ export const STANDARD_RAW = "raw";
28
+ const STANDARD_FORMAT = /^[a-z0-9][a-z0-9-]*-seed-standard@[1-9]\d*$/u;
29
+ /** The git identity and configuration of the scratch working copy: nothing of the machine's git configuration reaches it. */
30
+ const SCRATCH_GIT = Object.freeze({
31
+ GIT_AUTHOR_NAME: "starci-seed",
32
+ GIT_AUTHOR_EMAIL: "seed@starci.invalid",
33
+ GIT_COMMITTER_NAME: "starci-seed",
34
+ GIT_COMMITTER_EMAIL: "seed@starci.invalid",
35
+ GIT_CONFIG_NOSYSTEM: "1",
36
+ });
37
+ /**
38
+ * Writes `content` into `outDir` as a seed-standard: the entries go through `createGitDriver` into a scratch working copy
39
+ * (plaintext, the standard's purpose), and its `manifest.json`, `data/`, `blobs/` and `index/` replace those of `outDir`.
40
+ * A format that is no standard's is refused `DATA_FORM_REFUSED`; a repeated key or a set mixing forms is the manifest
41
+ * builder's TypeError.
42
+ */
43
+ export async function renderStandard(content, outDir, options = {}) {
44
+ if (!STANDARD_FORMAT.test(content.format))
45
+ throw new DataRefusal("DATA_FORM_REFUSED", "configuration", { format: content.format, reason: "a standard's format is <name>-seed-standard@<major>" });
46
+ const builder = new ManifestBuilder();
47
+ const spool = memorySpool();
48
+ for (const item of content.entries) {
49
+ builder.add(item.store, item.entry);
50
+ await spool.append(item);
51
+ }
52
+ const manifest = builder.build({ format: content.format, purpose: "seed-standard", takenAt: STANDARD_TAKEN_AT, source: { project: content.project, environment: STANDARD_ENVIRONMENT } });
53
+ const scratch = mkdtempSync(join(options.scratch ?? tmpdir(), "seed-standard-"));
54
+ try {
55
+ const config = join(scratch, "gitconfig");
56
+ writeFileSync(config, "");
57
+ const checkout = join(scratch, "copy");
58
+ const driver = createGitDriver({ id: content.format, checkout, env: { ...SCRATCH_GIT, GIT_CONFIG_GLOBAL: config }, ...(options.run === undefined ? {} : { run: options.run }) });
59
+ await driver.write(spooledSource(manifest, spool), { recipients: [], dryRun: false });
60
+ mkdirSync(outDir, { recursive: true });
61
+ for (const name of STANDARD_OUTPUTS) {
62
+ rmSync(join(outDir, name), { recursive: true, force: true });
63
+ if (existsSync(join(checkout, name)))
64
+ cpSync(join(checkout, name), join(outDir, name), { recursive: true });
65
+ }
66
+ }
67
+ finally {
68
+ rmSync(scratch, { recursive: true, force: true });
69
+ }
70
+ }
71
+ const ADAPTER_USAGE = "usage: node adapter/main.ts [--raw <dir>] [--out <dir>] (defaults: raw and the repository root, from the repository root)";
72
+ /** The `--raw` and `--out` of an adapter run, or a usage problem. */
73
+ function adapterArgs(argv) {
74
+ const values = { "--raw": STANDARD_RAW, "--out": "." };
75
+ for (let at = 0; at < argv.length; at += 2) {
76
+ const flag = String(argv[at]);
77
+ const value = argv[at + 1];
78
+ if (!(flag in values) || value === undefined || value.startsWith("--"))
79
+ return `${flag} is no flag of an adapter run, or has no value`;
80
+ values[flag] = value;
81
+ }
82
+ return { raw: String(values["--raw"]), out: String(values["--out"]) };
83
+ }
84
+ /**
85
+ * The body of an adapter's `main.ts`: `process.exitCode = await runStandardAdapter(convert, process.argv.slice(2))`.
86
+ * Converts `--raw` (default `raw`) and renders the standard into `--out` (default `.`, the repository root): exit 0;
87
+ * a usage problem is 2, a failed convert or render 1, with the refusal's code or the error on one line.
88
+ */
89
+ export async function runStandardAdapter(convert, argv, io = {}) {
90
+ const print = io.print ?? ((line) => void process.stderr.write(`${line}\n`));
91
+ const args = adapterArgs(argv);
92
+ if (typeof args === "string") {
93
+ print(`${args}; ${ADAPTER_USAGE}`);
94
+ return 2;
95
+ }
96
+ const cwd = io.cwd ?? process.cwd();
97
+ try {
98
+ await renderStandard(await convert(resolve(cwd, args.raw)), resolve(cwd, args.out));
99
+ return 0;
100
+ }
101
+ catch (cause) {
102
+ print(`the adapter failed: ${cause instanceof DataRefusal ? cause.code : String(cause)}`);
103
+ return 1;
104
+ }
105
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/seed",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "The data standard of a StarCi project in one package: the two kinds of seed, the standard seed (loaded once by the bring-up) and the backup seed (written by the scheduled job, brought back by a sync). The ports (store and driver adapters, one export to several copies, the copy contract and the line protocol), in-memory references with the store and driver contract suites under ./testing, a git driver (sealed by purpose with sops and age) under ./git, and the postgres store (the whole relational database as deterministic per-table rows) under ./postgres.",
5
5
  "keywords": [
6
6
  "seed",
@@ -82,6 +82,6 @@
82
82
  "access": "public",
83
83
  "provenance": true
84
84
  },
85
- "gitHead": "8fd394ebd5c80b1107bd85fa53303332b443de62",
86
- "starciSource": "f37d261720b75e63c78d2c82c2c2cbfb9255fae9a52a4c897c97fa3c8e33c4e9"
85
+ "gitHead": "018abe9f5bb449009b53897924abecaa64280aef",
86
+ "starciSource": "af5a83287e764db366a30cf4ccde45e7b9dfb9ddc20e70cde410ddcc4a96a180"
87
87
  }