@jam-overture/loom 0.1.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/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- package/package.json +160 -0
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { type Result } from "../result.js";
|
|
2
|
+
import type { FileSystem } from "./filesystem.js";
|
|
3
|
+
import { type CliError } from "./plan.js";
|
|
4
|
+
/**
|
|
5
|
+
* Parse, plan, write — in that order, and only writing once the whole plan is
|
|
6
|
+
* known to be safe. A command that would clash with an existing file writes
|
|
7
|
+
* nothing at all rather than leaving a directory half-scaffolded.
|
|
8
|
+
*/
|
|
9
|
+
export declare const CLI_USAGE = "loom \u2014 scaffolding for the Loom primitive registry\n\nUsage:\n loom init [--dir <directory>]\n loom add primitive <type> [--dir <directory>]\n loom --help\n\nOptions:\n --dir <directory> Where the Loom source lives (default: loom)\n\ninit writes a starter primitive, a generated registry, and a conformance test\ninto <directory>/primitives. add primitive declares one more and\nregenerates the registry from the directory's contents.\n\nA type is dot-namespaced kebab-case: app.card, commerce.product-card.\nloom.* is the framework's own namespace and is refused \u2014 those\nnames belong to the primitives @jam-overture/loom already registers.";
|
|
10
|
+
export type CliReport = {
|
|
11
|
+
readonly written: readonly string[];
|
|
12
|
+
readonly notes: readonly string[];
|
|
13
|
+
readonly usage: boolean;
|
|
14
|
+
};
|
|
15
|
+
export declare const describeCliError: (error: CliError) => string;
|
|
16
|
+
export declare const runCli: (argv: readonly string[], filesystem: FileSystem) => Promise<Result<CliReport, CliError>>;
|
|
17
|
+
//# sourceMappingURL=run.d.ts.map
|
package/dist/cli/run.js
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { assertNever, err, ok } from "../result.js";
|
|
2
|
+
import { DEFAULT_DIRECTORY, parseArguments } from "./args.js";
|
|
3
|
+
import { FRAMEWORK_NAMESPACE, hostAlternativeFor, HOST_NAMESPACE } from "./namespace.js";
|
|
4
|
+
import { planCommand, PRIMITIVES_DIRECTORY } from "./plan.js";
|
|
5
|
+
/**
|
|
6
|
+
* Parse, plan, write — in that order, and only writing once the whole plan is
|
|
7
|
+
* known to be safe. A command that would clash with an existing file writes
|
|
8
|
+
* nothing at all rather than leaving a directory half-scaffolded.
|
|
9
|
+
*/
|
|
10
|
+
export const CLI_USAGE = `loom — scaffolding for the Loom primitive registry
|
|
11
|
+
|
|
12
|
+
Usage:
|
|
13
|
+
loom init [--dir <directory>]
|
|
14
|
+
loom add primitive <type> [--dir <directory>]
|
|
15
|
+
loom --help
|
|
16
|
+
|
|
17
|
+
Options:
|
|
18
|
+
--dir <directory> Where the Loom source lives (default: ${DEFAULT_DIRECTORY})
|
|
19
|
+
|
|
20
|
+
init writes a starter primitive, a generated registry, and a conformance test
|
|
21
|
+
into <directory>/${PRIMITIVES_DIRECTORY}. add primitive declares one more and
|
|
22
|
+
regenerates the registry from the directory's contents.
|
|
23
|
+
|
|
24
|
+
A type is dot-namespaced kebab-case: ${HOST_NAMESPACE}.card, commerce.product-card.
|
|
25
|
+
${FRAMEWORK_NAMESPACE}.* is the framework's own namespace and is refused — those
|
|
26
|
+
names belong to the primitives @jam-overture/loom already registers.`;
|
|
27
|
+
export const describeCliError = (error) => {
|
|
28
|
+
switch (error.code) {
|
|
29
|
+
case "unknown-command":
|
|
30
|
+
return `"${error.given}" is not a loom command — run loom --help`;
|
|
31
|
+
case "missing-argument":
|
|
32
|
+
return `${error.argument} is required — run loom --help`;
|
|
33
|
+
case "unexpected-argument":
|
|
34
|
+
return `"${error.given}" was not expected — run loom --help`;
|
|
35
|
+
case "invalid-primitive-type":
|
|
36
|
+
return `"${error.type}" is not a valid primitive type — expected dot-namespaced kebab-case, like commerce.product-card`;
|
|
37
|
+
case "reserved-primitive-type":
|
|
38
|
+
return `"${error.type}" is reserved: its module would overwrite the generated registry`;
|
|
39
|
+
case "framework-namespace":
|
|
40
|
+
return `"${error.type}" is in the framework's namespace — @jam-overture/loom registers ${FRAMEWORK_NAMESPACE}.* and a registry refuses two definitions with one type. Try "${hostAlternativeFor(error.type)}"`;
|
|
41
|
+
case "already-registered":
|
|
42
|
+
return `"${error.type}" is already declared — edit its definition rather than regenerating it`;
|
|
43
|
+
case "file-exists":
|
|
44
|
+
return `${error.path} already exists; nothing was written`;
|
|
45
|
+
case "filesystem-failed":
|
|
46
|
+
return `could not write ${error.path}: ${error.detail}`;
|
|
47
|
+
default:
|
|
48
|
+
return assertNever(error, "describeCliError");
|
|
49
|
+
}
|
|
50
|
+
};
|
|
51
|
+
export const runCli = async (argv, filesystem) => {
|
|
52
|
+
const command = parseArguments(argv);
|
|
53
|
+
if (!command.ok)
|
|
54
|
+
return command;
|
|
55
|
+
if (command.value.kind === "help") {
|
|
56
|
+
return ok({ written: [], notes: [CLI_USAGE], usage: true });
|
|
57
|
+
}
|
|
58
|
+
const listed = await filesystem.list(command.value.directory);
|
|
59
|
+
if (!listed.ok) {
|
|
60
|
+
return err({ code: "filesystem-failed", path: command.value.directory, detail: listed.error });
|
|
61
|
+
}
|
|
62
|
+
const plan = planCommand(command.value, listed.value);
|
|
63
|
+
if (!plan.ok)
|
|
64
|
+
return plan;
|
|
65
|
+
const written = [];
|
|
66
|
+
for (const file of plan.value.files) {
|
|
67
|
+
const wrote = await filesystem.write(file.path, file.contents);
|
|
68
|
+
if (!wrote.ok) {
|
|
69
|
+
return err({ code: "filesystem-failed", path: file.path, detail: wrote.error });
|
|
70
|
+
}
|
|
71
|
+
written.push(file.path);
|
|
72
|
+
}
|
|
73
|
+
return ok({ written, notes: plan.value.notes, usage: false });
|
|
74
|
+
};
|
|
75
|
+
//# sourceMappingURL=run.js.map
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the CLI writes, as pure functions of a name.
|
|
3
|
+
*
|
|
4
|
+
* Every template is a string a host will read, edit, and keep, so they are held
|
|
5
|
+
* to the same standard as the runtime: no dead imports, no placeholder that
|
|
6
|
+
* typechecks only after a rewrite, and a generated file that says it is
|
|
7
|
+
* generated. A scaffold that has to be repaired before it compiles teaches the
|
|
8
|
+
* wrong thing about the contract on the first contact with it.
|
|
9
|
+
*/
|
|
10
|
+
export type PrimitiveNames = {
|
|
11
|
+
/** The primitive type, exactly as a tree will address it. */
|
|
12
|
+
readonly type: string;
|
|
13
|
+
/**
|
|
14
|
+
* The module basename, which is the type verbatim: `commerce.product-card.ts`.
|
|
15
|
+
*
|
|
16
|
+
* Dots survive where a slug would not. Folding `.` to `-` is lossy — nothing
|
|
17
|
+
* can tell whether `commerce-product-card` was `commerce.product-card` or
|
|
18
|
+
* `commerce-product.card` — and the registry is regenerated from the directory
|
|
19
|
+
* listing, so that round trip has to be exact.
|
|
20
|
+
*/
|
|
21
|
+
readonly module: string;
|
|
22
|
+
/** The exported binding: `commerce.product-card` → `commerceProductCard`. */
|
|
23
|
+
readonly exportName: string;
|
|
24
|
+
};
|
|
25
|
+
export declare const namesFor: (type: string) => PrimitiveNames;
|
|
26
|
+
export declare const primitiveModule: (names: PrimitiveNames) => string;
|
|
27
|
+
export declare const REGISTRY_MODULE = "registry.ts";
|
|
28
|
+
export declare const CONFORMANCE_TEST_MODULE = "registry.test.ts";
|
|
29
|
+
/**
|
|
30
|
+
* Reserved because the registry and its test share the primitives directory, and
|
|
31
|
+
* `registry` and `registry.test` are both valid primitive types — so a primitive
|
|
32
|
+
* named either one would be written over the file that registers it.
|
|
33
|
+
*/
|
|
34
|
+
export declare const RESERVED_PRIMITIVE_TYPES: readonly string[];
|
|
35
|
+
export declare const registryModule: (primitives: readonly PrimitiveNames[]) => string;
|
|
36
|
+
/**
|
|
37
|
+
* The generated test is the point of the generated scaffold. `auditRegistry`
|
|
38
|
+
* reports and never enforces (0012), so a deployment only benefits from it if
|
|
39
|
+
* something actually runs it — and a host is far more likely to keep a test that
|
|
40
|
+
* was there from the first commit than to add one later.
|
|
41
|
+
*/
|
|
42
|
+
export declare const conformanceTest: () => string;
|
|
43
|
+
//# sourceMappingURL=templates.d.ts.map
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the CLI writes, as pure functions of a name.
|
|
3
|
+
*
|
|
4
|
+
* Every template is a string a host will read, edit, and keep, so they are held
|
|
5
|
+
* to the same standard as the runtime: no dead imports, no placeholder that
|
|
6
|
+
* typechecks only after a rewrite, and a generated file that says it is
|
|
7
|
+
* generated. A scaffold that has to be repaired before it compiles teaches the
|
|
8
|
+
* wrong thing about the contract on the first contact with it.
|
|
9
|
+
*/
|
|
10
|
+
const capitalize = (segment) => `${segment.slice(0, 1).toUpperCase()}${segment.slice(1)}`;
|
|
11
|
+
const camelCase = (type) => {
|
|
12
|
+
const words = type.split(/[.-]/).filter((word) => word.length > 0);
|
|
13
|
+
const [first, ...rest] = words;
|
|
14
|
+
return `${first ?? ""}${rest.map(capitalize).join("")}`;
|
|
15
|
+
};
|
|
16
|
+
export const namesFor = (type) => ({
|
|
17
|
+
type,
|
|
18
|
+
module: `${type}.ts`,
|
|
19
|
+
exportName: camelCase(type),
|
|
20
|
+
});
|
|
21
|
+
export const primitiveModule = (names) => `import { createElement } from "react"
|
|
22
|
+
import { z } from "zod"
|
|
23
|
+
|
|
24
|
+
import type { LoomPrimitiveProps } from "@jam-overture/loom/react"
|
|
25
|
+
import { definePrimitive } from "@jam-overture/loom/sdk"
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Every prop a tree may set on this primitive. The render seam refuses a node
|
|
29
|
+
* whose props do not satisfy this schema, so it is the one place that decides
|
|
30
|
+
* what AI is allowed to configure here.
|
|
31
|
+
*/
|
|
32
|
+
const props = z.object({}).strict()
|
|
33
|
+
|
|
34
|
+
type Props = z.infer<typeof props>
|
|
35
|
+
|
|
36
|
+
export const ${names.exportName} = definePrimitive({
|
|
37
|
+
type: "${names.type}",
|
|
38
|
+
/** One line. This is what a model reads when choosing between primitives. */
|
|
39
|
+
description: "Describe what ${names.type} is for",
|
|
40
|
+
props,
|
|
41
|
+
/** Name a slot here for every region this primitive projects children into. */
|
|
42
|
+
slots: [],
|
|
43
|
+
component: ({ loom, children }: LoomPrimitiveProps<Props>) =>
|
|
44
|
+
/**
|
|
45
|
+
* Spreading \`loom.editable\` is the edit-mode contract: without it this
|
|
46
|
+
* primitive renders correctly and is invisible to the portal. Read declared
|
|
47
|
+
* props off the \`props\` bag — they are never spread onto the element.
|
|
48
|
+
*/
|
|
49
|
+
createElement("div", { ...loom.editable }, children),
|
|
50
|
+
})
|
|
51
|
+
`;
|
|
52
|
+
export const REGISTRY_MODULE = "registry.ts";
|
|
53
|
+
export const CONFORMANCE_TEST_MODULE = "registry.test.ts";
|
|
54
|
+
/**
|
|
55
|
+
* Reserved because the registry and its test share the primitives directory, and
|
|
56
|
+
* `registry` and `registry.test` are both valid primitive types — so a primitive
|
|
57
|
+
* named either one would be written over the file that registers it.
|
|
58
|
+
*/
|
|
59
|
+
export const RESERVED_PRIMITIVE_TYPES = ["registry", "registry.test"];
|
|
60
|
+
export const registryModule = (primitives) => {
|
|
61
|
+
const sorted = [...primitives].sort((left, right) => left.type.localeCompare(right.type));
|
|
62
|
+
const imports = sorted
|
|
63
|
+
.map((names) => `import { ${names.exportName} } from "./${names.type}.js"`)
|
|
64
|
+
.join("\n");
|
|
65
|
+
const registered = sorted.map((names) => ` ${names.exportName},`).join("\n");
|
|
66
|
+
return `/**
|
|
67
|
+
* Generated by \`loom add primitive\`. Edit the definitions, not this file — it is
|
|
68
|
+
* rewritten from the contents of this directory every time a primitive is added.
|
|
69
|
+
*/
|
|
70
|
+
|
|
71
|
+
import { createPrimitiveRegistry, describeRegistryError } from "@jam-overture/loom/sdk"
|
|
72
|
+
${imports === "" ? "" : `\n${imports}\n`}
|
|
73
|
+
const built = createPrimitiveRegistry([
|
|
74
|
+
${registered}
|
|
75
|
+
])
|
|
76
|
+
|
|
77
|
+
if (!built.ok) {
|
|
78
|
+
throw new Error(\`loom: the primitive registry was refused — \${describeRegistryError(built.error)}\`)
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export const registry = built.value
|
|
82
|
+
`;
|
|
83
|
+
};
|
|
84
|
+
/**
|
|
85
|
+
* The generated test is the point of the generated scaffold. `auditRegistry`
|
|
86
|
+
* reports and never enforces (0012), so a deployment only benefits from it if
|
|
87
|
+
* something actually runs it — and a host is far more likely to keep a test that
|
|
88
|
+
* was there from the first commit than to add one later.
|
|
89
|
+
*/
|
|
90
|
+
export const conformanceTest = () => `import { describe, expect, it } from "vitest"
|
|
91
|
+
|
|
92
|
+
import { auditRegistry, describeRegistryAudit } from "@jam-overture/loom/sdk"
|
|
93
|
+
|
|
94
|
+
import { registry } from "./registry.js"
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Generated by \`loom init\`. Keep it: a primitive that ignores \`loom.editable\`
|
|
98
|
+
* renders perfectly and is invisible to the portal, with no error anywhere. This
|
|
99
|
+
* is the only thing that catches it, and it catches it at build time rather than
|
|
100
|
+
* when someone is trying to edit a page.
|
|
101
|
+
*/
|
|
102
|
+
describe("the primitive registry", () => {
|
|
103
|
+
it("registers primitives that are all visible to the portal", () => {
|
|
104
|
+
const audit = auditRegistry(registry)
|
|
105
|
+
|
|
106
|
+
expect(audit.notDecorated, describeRegistryAudit(audit)).toEqual([])
|
|
107
|
+
})
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* \`not-probeable\` is neither a pass nor a failure — a hook-using or class
|
|
111
|
+
* component cannot be called outside a renderer. Assert the list you expect so
|
|
112
|
+
* a newly unprobeable primitive is a decision rather than a surprise.
|
|
113
|
+
*/
|
|
114
|
+
it("has no primitives the probe could not judge", () => {
|
|
115
|
+
const audit = auditRegistry(registry)
|
|
116
|
+
|
|
117
|
+
expect(audit.notProbeable, describeRegistryAudit(audit)).toEqual([])
|
|
118
|
+
})
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The one that stops a page rather than a portal: a component that throws on a
|
|
122
|
+
* value its own schema accepts is one a tree the validator *accepted* can take
|
|
123
|
+
* down. If you add a hook-using primitive, the probe cannot tell it from a
|
|
124
|
+
* broken one and it will appear here — narrow this to the entries with
|
|
125
|
+
* \`everyConfiguration: false\`, which are the ones the audit is certain of.
|
|
126
|
+
*/
|
|
127
|
+
it("has no primitives that throw on props their own schema accepts", () => {
|
|
128
|
+
const audit = auditRegistry(registry)
|
|
129
|
+
|
|
130
|
+
expect(audit.throwsOnDeclaredProps, describeRegistryAudit(audit)).toEqual([])
|
|
131
|
+
})
|
|
132
|
+
})
|
|
133
|
+
`;
|
|
134
|
+
//# sourceMappingURL=templates.js.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Naming every member of a union, so that something can walk it.
|
|
3
|
+
*
|
|
4
|
+
* A union of string literals is exhaustive at compile time in the direction the
|
|
5
|
+
* runtime was designed for: a `switch` over it cannot miss a case. It is not
|
|
6
|
+
* enumerable in the other direction. Anything that wants to *walk* the members
|
|
7
|
+
* rather than react to one — a page describing what a host must handle, a
|
|
8
|
+
* dashboard that needs every bucket to exist before the first request, a
|
|
9
|
+
* conformance check — has to keep its own copy of the list, in its own order,
|
|
10
|
+
* with nothing to fail when a new member lands.
|
|
11
|
+
*
|
|
12
|
+
* Where the members already come from a schema there is no problem: the list is
|
|
13
|
+
* `schema.options` and completeness is not a claim anyone makes. This is for the
|
|
14
|
+
* unions that cannot have one, because their members carry values a schema
|
|
15
|
+
* cannot describe.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* A list that has to name every member of a union, checked where it is written.
|
|
19
|
+
*
|
|
20
|
+
* Curried because TypeScript infers all of a call's type arguments or none of
|
|
21
|
+
* them, and the union has to be named while the list is inferred.
|
|
22
|
+
*
|
|
23
|
+
* The completeness check is the second parameter, and it is the whole point: it
|
|
24
|
+
* is an empty rest parameter while the list is complete, and a *required*
|
|
25
|
+
* argument the moment a member is missing, so the call itself stops compiling.
|
|
26
|
+
* The argument it then asks for is named `missing` and typed as the member that
|
|
27
|
+
* is missing, which is what the signature shows a reader who goes to look.
|
|
28
|
+
*
|
|
29
|
+
* ```ts
|
|
30
|
+
* export const KINDS: readonly Kind[] = everyMemberOf<Kind>()(["held", "refused"])
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
export declare const everyMemberOf: <Union extends string>() => <const List extends readonly Union[]>(list: List, ..._complete: [Union] extends [List[number]] ? [] : [missing: Exclude<Union, List[number]>]) => List;
|
|
34
|
+
//# sourceMappingURL=closed-set.d.ts.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Naming every member of a union, so that something can walk it.
|
|
3
|
+
*
|
|
4
|
+
* A union of string literals is exhaustive at compile time in the direction the
|
|
5
|
+
* runtime was designed for: a `switch` over it cannot miss a case. It is not
|
|
6
|
+
* enumerable in the other direction. Anything that wants to *walk* the members
|
|
7
|
+
* rather than react to one — a page describing what a host must handle, a
|
|
8
|
+
* dashboard that needs every bucket to exist before the first request, a
|
|
9
|
+
* conformance check — has to keep its own copy of the list, in its own order,
|
|
10
|
+
* with nothing to fail when a new member lands.
|
|
11
|
+
*
|
|
12
|
+
* Where the members already come from a schema there is no problem: the list is
|
|
13
|
+
* `schema.options` and completeness is not a claim anyone makes. This is for the
|
|
14
|
+
* unions that cannot have one, because their members carry values a schema
|
|
15
|
+
* cannot describe.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* A list that has to name every member of a union, checked where it is written.
|
|
19
|
+
*
|
|
20
|
+
* Curried because TypeScript infers all of a call's type arguments or none of
|
|
21
|
+
* them, and the union has to be named while the list is inferred.
|
|
22
|
+
*
|
|
23
|
+
* The completeness check is the second parameter, and it is the whole point: it
|
|
24
|
+
* is an empty rest parameter while the list is complete, and a *required*
|
|
25
|
+
* argument the moment a member is missing, so the call itself stops compiling.
|
|
26
|
+
* The argument it then asks for is named `missing` and typed as the member that
|
|
27
|
+
* is missing, which is what the signature shows a reader who goes to look.
|
|
28
|
+
*
|
|
29
|
+
* ```ts
|
|
30
|
+
* export const KINDS: readonly Kind[] = everyMemberOf<Kind>()(["held", "refused"])
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
export const everyMemberOf = () => (list, ..._complete) => list;
|
|
34
|
+
//# sourceMappingURL=closed-set.js.map
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import type { ZodType, ZodTypeDef } from "zod";
|
|
2
|
+
import { type CataloguedProp } from "../catalogue.js";
|
|
3
|
+
import type { JsonObject, JsonValue } from "../json.js";
|
|
4
|
+
import { type Result } from "../result.js";
|
|
5
|
+
import { type SourceId } from "./source.js";
|
|
6
|
+
/**
|
|
7
|
+
* The host's half of the data seam: what answers a binding.
|
|
8
|
+
*
|
|
9
|
+
* An adapter is the only place in a render that does IO, and it is foreign code
|
|
10
|
+
* — a query against someone's database, a call to an integration that is having
|
|
11
|
+
* a bad afternoon. Everything here exists to keep that from reaching the page:
|
|
12
|
+
* the params it is handed are validated first, the answer it gives back is
|
|
13
|
+
* validated after, and a throw is caught and reported like any other refusal.
|
|
14
|
+
*
|
|
15
|
+
* The registration shape deliberately mirrors `definePrimitive`. A source
|
|
16
|
+
* declares an id, one line about itself, what it accepts and what it answers;
|
|
17
|
+
* the registry erases the types and is the only thing that hands out either
|
|
18
|
+
* half, for the same soundness reason the primitive registry gives.
|
|
19
|
+
*/
|
|
20
|
+
export type SourceRequest<TParams> = {
|
|
21
|
+
readonly params: TParams;
|
|
22
|
+
/** The render request's opaque host context — audience, locale, tenant. */
|
|
23
|
+
readonly context: JsonObject | undefined;
|
|
24
|
+
/**
|
|
25
|
+
* Aborted once the render has stopped waiting for this binding, which it will
|
|
26
|
+
* (0140). An adapter that ignores it still cannot delay the page; what it holds
|
|
27
|
+
* on to is a connection whose answer nothing will read. Pass it to whatever
|
|
28
|
+
* does the IO — `fetch`, a driver's query options — and the pool gets it back.
|
|
29
|
+
*/
|
|
30
|
+
readonly signal: AbortSignal | undefined;
|
|
31
|
+
};
|
|
32
|
+
/** What an adapter says when it cannot answer. */
|
|
33
|
+
export type SourceFailure = {
|
|
34
|
+
/**
|
|
35
|
+
* `unavailable` is "ask again later" — a timeout, a dead connection.
|
|
36
|
+
* `refused` is "not for you" — an integration nobody connected, a record this
|
|
37
|
+
* audience may not see. They are separate because a primitive shows different
|
|
38
|
+
* things for them, and because only one of the two is worth retrying.
|
|
39
|
+
*/
|
|
40
|
+
readonly code: "unavailable" | "refused";
|
|
41
|
+
readonly detail: string;
|
|
42
|
+
};
|
|
43
|
+
export interface DataAdapter<TParams = JsonObject, TAnswer extends JsonValue = JsonValue> {
|
|
44
|
+
readonly fetch: (request: SourceRequest<TParams>) => Promise<Result<TAnswer, SourceFailure>>;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Why a binding has no value. Every one of these is something a primitive may
|
|
48
|
+
* be told about and a diagnostic says out loud; none of them is an exception
|
|
49
|
+
* anyone catches.
|
|
50
|
+
*
|
|
51
|
+
* `no-such-source` and `not-resolved` are the pair worth keeping apart, and they
|
|
52
|
+
* were one code until 12 September. An unregistered source is fixed in the
|
|
53
|
+
* registry by whoever owns the data; a binding nothing resolved is fixed in the
|
|
54
|
+
* composition root by whoever wired the render — a caller that resolved a
|
|
55
|
+
* different plan than the one it is rendering. Sharing a code made a diagnostic
|
|
56
|
+
* say "no source is registered for it — this binding was never resolved", which
|
|
57
|
+
* is two sentences contradicting each other, and pooled the two for anything
|
|
58
|
+
* counting reasons.
|
|
59
|
+
*/
|
|
60
|
+
export type DataUnavailable = {
|
|
61
|
+
readonly reason: "no-such-source" | "not-resolved" | "invalid-params" | "invalid-answer" | "adapter-threw" | SourceFailure["code"];
|
|
62
|
+
readonly detail: string;
|
|
63
|
+
};
|
|
64
|
+
export declare const describeDataUnavailable: (unavailable: DataUnavailable) => string;
|
|
65
|
+
export type SourceDefinition<TParams, TAnswer extends JsonValue> = {
|
|
66
|
+
readonly id: string;
|
|
67
|
+
/** One line, for the catalogue. A model choosing a source has this to go on. */
|
|
68
|
+
readonly description: string;
|
|
69
|
+
/**
|
|
70
|
+
* What the tree may ask with. Required, with no "anything" option: params are
|
|
71
|
+
* AI-authored, and a source that declines to say what it accepts is asking the
|
|
72
|
+
* deployment to trust a model's guess about its own query.
|
|
73
|
+
*/
|
|
74
|
+
readonly params: ZodType<TParams, ZodTypeDef, unknown>;
|
|
75
|
+
/**
|
|
76
|
+
* What it promises to answer with. Checked at the seam even though the adapter
|
|
77
|
+
* is typed by it, because the adapter's type is a claim about a database and
|
|
78
|
+
* the schema is the only thing that makes it true on the day the column
|
|
79
|
+
* changed.
|
|
80
|
+
*/
|
|
81
|
+
readonly answers: ZodType<TAnswer, ZodTypeDef, unknown>;
|
|
82
|
+
readonly adapter: DataAdapter<TParams, TAnswer>;
|
|
83
|
+
};
|
|
84
|
+
/**
|
|
85
|
+
* A definition with its types erased, which is what a heterogeneous registry can
|
|
86
|
+
* hold. `defineSource` is the only way to build one, so the erasure happens once,
|
|
87
|
+
* where both schemas and the adapter are still in hand and can be proved to agree.
|
|
88
|
+
*/
|
|
89
|
+
export type SourceEntry = {
|
|
90
|
+
readonly id: string;
|
|
91
|
+
readonly description: string;
|
|
92
|
+
readonly declaredParams: readonly CataloguedProp[] | undefined;
|
|
93
|
+
/** Total: validates, calls, catches, validates again. Never rejects. */
|
|
94
|
+
readonly answer: (params: JsonObject, context: JsonObject | undefined, signal?: AbortSignal) => Promise<Result<JsonValue, DataUnavailable>>;
|
|
95
|
+
};
|
|
96
|
+
/**
|
|
97
|
+
* Declares a source. The generic parameters are inferred from the schemas, so
|
|
98
|
+
* the adapter is checked against what its own declaration produces at the point
|
|
99
|
+
* of declaration rather than at the point of registration.
|
|
100
|
+
*/
|
|
101
|
+
export declare const defineSource: <TParams, TAnswer extends JsonValue>(definition: SourceDefinition<TParams, TAnswer>) => SourceEntry;
|
|
102
|
+
export type RegisteredSource = SourceEntry & {
|
|
103
|
+
readonly id: SourceId;
|
|
104
|
+
};
|
|
105
|
+
export type DataRegistryError = {
|
|
106
|
+
readonly code: "invalid-source-id";
|
|
107
|
+
readonly id: string;
|
|
108
|
+
} | {
|
|
109
|
+
readonly code: "duplicate-source-id";
|
|
110
|
+
readonly id: string;
|
|
111
|
+
};
|
|
112
|
+
export declare const describeDataRegistryError: (error: DataRegistryError) => string;
|
|
113
|
+
export interface DataRegistry {
|
|
114
|
+
readonly source: (id: SourceId) => RegisteredSource | undefined;
|
|
115
|
+
/** In registration order, so a catalogue reads predictably. */
|
|
116
|
+
readonly sources: readonly RegisteredSource[];
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Building the registry is pure and calls no adapter, so registering cannot run
|
|
120
|
+
* someone's query as a side effect of an import.
|
|
121
|
+
*/
|
|
122
|
+
export declare const createDataRegistry: (entries: readonly SourceEntry[]) => Result<DataRegistry, DataRegistryError>;
|
|
123
|
+
//# sourceMappingURL=adapter.d.ts.map
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { catalogueFields } from "../catalogue.js";
|
|
2
|
+
import { err, ok } from "../result.js";
|
|
3
|
+
import { SOURCE_ID_EXPECTATION, sourceIdSchema } from "./source.js";
|
|
4
|
+
export const describeDataUnavailable = (unavailable) => {
|
|
5
|
+
switch (unavailable.reason) {
|
|
6
|
+
case "no-such-source":
|
|
7
|
+
return `no source is registered for it — ${unavailable.detail}`;
|
|
8
|
+
case "not-resolved":
|
|
9
|
+
return `nothing resolved it — ${unavailable.detail}`;
|
|
10
|
+
case "invalid-params":
|
|
11
|
+
return `the params in the tree are not what the source accepts — ${unavailable.detail}`;
|
|
12
|
+
case "invalid-answer":
|
|
13
|
+
return `the source answered with something its own schema refuses — ${unavailable.detail}`;
|
|
14
|
+
case "adapter-threw":
|
|
15
|
+
return `the source threw instead of answering — ${unavailable.detail}`;
|
|
16
|
+
case "unavailable":
|
|
17
|
+
return `the source could not be reached — ${unavailable.detail}`;
|
|
18
|
+
case "refused":
|
|
19
|
+
return `the source refused — ${unavailable.detail}`;
|
|
20
|
+
}
|
|
21
|
+
};
|
|
22
|
+
const firstIssue = (error) => {
|
|
23
|
+
const [issue] = error.issues;
|
|
24
|
+
if (!issue)
|
|
25
|
+
return "refused, without saying why";
|
|
26
|
+
const path = issue.path.length === 0 ? "" : `${issue.path.map(String).join(".")}: `;
|
|
27
|
+
return `${path}${issue.message}`;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* Declares a source. The generic parameters are inferred from the schemas, so
|
|
31
|
+
* the adapter is checked against what its own declaration produces at the point
|
|
32
|
+
* of declaration rather than at the point of registration.
|
|
33
|
+
*/
|
|
34
|
+
export const defineSource = (definition) => ({
|
|
35
|
+
id: definition.id,
|
|
36
|
+
description: definition.description,
|
|
37
|
+
declaredParams: catalogueFields(definition.params),
|
|
38
|
+
answer: async (params, context, signal) => {
|
|
39
|
+
const accepted = definition.params.safeParse(params);
|
|
40
|
+
if (!accepted.success) {
|
|
41
|
+
return err({ reason: "invalid-params", detail: firstIssue(accepted.error) });
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The one `try` in the runtime's own code. Loom does not throw across a
|
|
45
|
+
* seam, but an adapter is not Loom's code, and a rejected promise from one
|
|
46
|
+
* host's integration must not be the reason a whole page 500s.
|
|
47
|
+
*/
|
|
48
|
+
let fetched;
|
|
49
|
+
try {
|
|
50
|
+
fetched = await definition.adapter.fetch({ params: accepted.data, context, signal });
|
|
51
|
+
}
|
|
52
|
+
catch (thrown) {
|
|
53
|
+
return err({
|
|
54
|
+
reason: "adapter-threw",
|
|
55
|
+
detail: thrown instanceof Error ? thrown.message : String(thrown),
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
if (!fetched.ok)
|
|
59
|
+
return err({ reason: fetched.error.code, detail: fetched.error.detail });
|
|
60
|
+
const answered = definition.answers.safeParse(fetched.value);
|
|
61
|
+
return answered.success
|
|
62
|
+
? ok(answered.data)
|
|
63
|
+
: err({ reason: "invalid-answer", detail: firstIssue(answered.error) });
|
|
64
|
+
},
|
|
65
|
+
});
|
|
66
|
+
export const describeDataRegistryError = (error) => error.code === "invalid-source-id"
|
|
67
|
+
? `"${error.id}" is not a valid source id — ${SOURCE_ID_EXPECTATION}`
|
|
68
|
+
: `"${error.id}" is registered twice; a binding naming it would reach whichever registration won`;
|
|
69
|
+
/**
|
|
70
|
+
* Building the registry is pure and calls no adapter, so registering cannot run
|
|
71
|
+
* someone's query as a side effect of an import.
|
|
72
|
+
*/
|
|
73
|
+
export const createDataRegistry = (entries) => {
|
|
74
|
+
const sources = [];
|
|
75
|
+
const byId = new Map();
|
|
76
|
+
for (const entry of entries) {
|
|
77
|
+
const id = sourceIdSchema.safeParse(entry.id);
|
|
78
|
+
if (!id.success)
|
|
79
|
+
return err({ code: "invalid-source-id", id: entry.id });
|
|
80
|
+
if (byId.has(id.data))
|
|
81
|
+
return err({ code: "duplicate-source-id", id: entry.id });
|
|
82
|
+
const registered = { ...entry, id: id.data };
|
|
83
|
+
byId.set(id.data, registered);
|
|
84
|
+
sources.push(registered);
|
|
85
|
+
}
|
|
86
|
+
return ok({
|
|
87
|
+
source: (id) => byId.get(id),
|
|
88
|
+
sources: Object.freeze(sources),
|
|
89
|
+
});
|
|
90
|
+
};
|
|
91
|
+
//# sourceMappingURL=adapter.js.map
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { type JsonObject } from "../json.js";
|
|
2
|
+
import { type Result } from "../result.js";
|
|
3
|
+
import { type BindingName, type SourceId } from "./source.js";
|
|
4
|
+
/**
|
|
5
|
+
* What a node asks the host to answer, as it appears in the tree.
|
|
6
|
+
*
|
|
7
|
+
* A binding is a *question*, never an answer: a registered source id and the
|
|
8
|
+
* parameters to ask it with. Nothing about the reply is in the tree, which is
|
|
9
|
+
* what keeps a tree a document rather than a cache — two deployments serving the
|
|
10
|
+
* same revision show the same page structure asking the same questions, and
|
|
11
|
+
* differ only where their data differs.
|
|
12
|
+
*
|
|
13
|
+
* ```json
|
|
14
|
+
* "loom:data": {
|
|
15
|
+
* "services": { "source": "catalogue.services", "params": { "limit": 6 } },
|
|
16
|
+
* "bio": { "source": "profile.field", "params": { "field": "bio" } }
|
|
17
|
+
* }
|
|
18
|
+
* ```
|
|
19
|
+
*
|
|
20
|
+
* Params are AI-authored like everything else in a tree, so a source declares
|
|
21
|
+
* what it accepts and the registry checks it (0058). An adapter that takes a
|
|
22
|
+
* free-form query string would be handing a model the keys to the host's data,
|
|
23
|
+
* which is the failure 0053 rejected for URLs in the same words.
|
|
24
|
+
*/
|
|
25
|
+
export type Binding = {
|
|
26
|
+
readonly source: SourceId;
|
|
27
|
+
readonly params: JsonObject;
|
|
28
|
+
};
|
|
29
|
+
/** Bindings on one node, by the name the primitive reads them under. */
|
|
30
|
+
export type NodeBindings = ReadonlyMap<BindingName, Binding>;
|
|
31
|
+
export type BindingError = {
|
|
32
|
+
/** The path of the offending entry, for a diagnostic a person can act on. */
|
|
33
|
+
readonly path: string;
|
|
34
|
+
readonly message: string;
|
|
35
|
+
};
|
|
36
|
+
export declare const describeBindingError: (error: BindingError) => string;
|
|
37
|
+
/**
|
|
38
|
+
* Parses the value of `loom:data`. Total, like every other parse of something
|
|
39
|
+
* that came out of storage: a malformed binding map is reported and the node
|
|
40
|
+
* renders without data, rather than throwing on a page nobody can then see.
|
|
41
|
+
*
|
|
42
|
+
* The whole map is refused together when any entry is bad. Answering half of a
|
|
43
|
+
* malformed declaration would hand a primitive a bag that satisfies neither
|
|
44
|
+
* what the author wrote nor what the schema says, and "some of your bindings
|
|
45
|
+
* silently did not happen" is the hardest kind of failure to notice.
|
|
46
|
+
*/
|
|
47
|
+
export declare const parseBindings: (declared: unknown) => Result<NodeBindings, BindingError>;
|
|
48
|
+
//# sourceMappingURL=binding.d.ts.map
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { jsonObjectSchema } from "../json.js";
|
|
3
|
+
import { err, ok } from "../result.js";
|
|
4
|
+
import { bindingNameSchema, sourceIdSchema } from "./source.js";
|
|
5
|
+
const bindingSchema = z.object({
|
|
6
|
+
source: sourceIdSchema,
|
|
7
|
+
params: jsonObjectSchema.optional(),
|
|
8
|
+
});
|
|
9
|
+
const bindingsSchema = z.record(bindingNameSchema, bindingSchema);
|
|
10
|
+
export const describeBindingError = (error) => `${error.path}: ${error.message}`;
|
|
11
|
+
/**
|
|
12
|
+
* Parses the value of `loom:data`. Total, like every other parse of something
|
|
13
|
+
* that came out of storage: a malformed binding map is reported and the node
|
|
14
|
+
* renders without data, rather than throwing on a page nobody can then see.
|
|
15
|
+
*
|
|
16
|
+
* The whole map is refused together when any entry is bad. Answering half of a
|
|
17
|
+
* malformed declaration would hand a primitive a bag that satisfies neither
|
|
18
|
+
* what the author wrote nor what the schema says, and "some of your bindings
|
|
19
|
+
* silently did not happen" is the hardest kind of failure to notice.
|
|
20
|
+
*/
|
|
21
|
+
export const parseBindings = (declared) => {
|
|
22
|
+
const parsed = bindingsSchema.safeParse(declared);
|
|
23
|
+
if (!parsed.success) {
|
|
24
|
+
const [issue] = parsed.error.issues;
|
|
25
|
+
return err({
|
|
26
|
+
path: issue && issue.path.length > 0 ? issue.path.map(String).join(".") : "loom:data",
|
|
27
|
+
message: issue?.message ?? "is not a map of binding names to sources",
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Zod types a record with a branded key as partial, so the values are
|
|
32
|
+
* `T | undefined` even though every key it produced came with one. Filtering
|
|
33
|
+
* rather than asserting keeps the one place that could be wrong honest.
|
|
34
|
+
*/
|
|
35
|
+
return ok(new Map(Object.entries(parsed.data).flatMap(([name, binding]) => binding
|
|
36
|
+
? [[name, { source: binding.source, params: binding.params ?? {} }]]
|
|
37
|
+
: [])));
|
|
38
|
+
};
|
|
39
|
+
//# sourceMappingURL=binding.js.map
|