@inventarch/cli 3.0.0 → 3.1.1
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/README.md +221 -23
- package/SPEC.md +39 -18
- package/assets/base/df626d1dc4949649ba7203842b29b4f064e0552e8db8c2c41ff74b6462b81b75.ia.tgz +0 -0
- package/assets/base.json +3 -3
- package/assets/host/f91ffe4c2071b196e925e93507bd661b3e09f5dc75392f7d6453fdbec5e28d62.tgz +0 -0
- package/assets/host.json +4 -4
- package/assets/vocabulary.json +152 -1
- package/dist/author.d.ts.map +1 -1
- package/dist/author.js +6 -7
- package/dist/author.js.map +1 -1
- package/dist/briefing.d.ts +2 -2
- package/dist/briefing.d.ts.map +1 -1
- package/dist/capture.d.ts +2 -2
- package/dist/capture.js +7 -7
- package/dist/commands.d.ts +7 -7
- package/dist/commands.d.ts.map +1 -1
- package/dist/commands.js +69 -30
- package/dist/commands.js.map +1 -1
- package/dist/consumer.d.ts +29 -25
- package/dist/consumer.d.ts.map +1 -1
- package/dist/consumer.js +40 -35
- package/dist/consumer.js.map +1 -1
- package/dist/decline.js +1 -1
- package/dist/distribute.d.ts +13 -14
- package/dist/distribute.d.ts.map +1 -1
- package/dist/distribute.js +17 -17
- package/dist/distribute.js.map +1 -1
- package/dist/doctor-user.d.ts +1 -1
- package/dist/doctor-user.d.ts.map +1 -1
- package/dist/doctor-user.js +2 -2
- package/dist/doctor-user.js.map +1 -1
- package/dist/doctor.d.ts +1 -1
- package/dist/doctor.d.ts.map +1 -1
- package/dist/doctor.js +53 -54
- package/dist/doctor.js.map +1 -1
- package/dist/format.js +3 -3
- package/dist/format.js.map +1 -1
- package/dist/home-remedy.d.ts +1 -1
- package/dist/home-remedy.js +1 -1
- package/dist/host-projection.d.ts +41 -38
- package/dist/host-projection.d.ts.map +1 -1
- package/dist/host-projection.js +84 -71
- package/dist/host-projection.js.map +1 -1
- package/dist/host.d.ts +37 -38
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +54 -57
- package/dist/host.js.map +1 -1
- package/dist/init.d.ts +69 -58
- package/dist/init.d.ts.map +1 -1
- package/dist/init.js +166 -107
- package/dist/init.js.map +1 -1
- package/dist/main.js +4 -4
- package/dist/main.js.map +1 -1
- package/dist/next.js +15 -15
- package/dist/next.js.map +1 -1
- package/dist/operation-help.d.ts +3 -3
- package/dist/operation-help.d.ts.map +1 -1
- package/dist/operation-help.js +9 -9
- package/dist/operation-help.js.map +1 -1
- package/dist/pack.js +6 -6
- package/dist/plugin-product.d.ts +3 -0
- package/dist/plugin-product.d.ts.map +1 -0
- package/dist/plugin-product.js +154 -0
- package/dist/plugin-product.js.map +1 -0
- package/dist/plugin-sources.d.ts +16 -0
- package/dist/plugin-sources.d.ts.map +1 -0
- package/dist/plugin-sources.js +120 -0
- package/dist/plugin-sources.js.map +1 -0
- package/dist/position.d.ts.map +1 -1
- package/dist/position.js +10 -11
- package/dist/position.js.map +1 -1
- package/dist/preview.d.ts +4 -4
- package/dist/preview.d.ts.map +1 -1
- package/dist/preview.js +27 -28
- package/dist/preview.js.map +1 -1
- package/dist/profile.d.ts +23 -23
- package/dist/profile.d.ts.map +1 -1
- package/dist/profile.js +53 -54
- package/dist/profile.js.map +1 -1
- package/dist/project.d.ts +7 -8
- package/dist/project.d.ts.map +1 -1
- package/dist/project.js +38 -28
- package/dist/project.js.map +1 -1
- package/dist/read.d.ts +1 -1
- package/dist/read.d.ts.map +1 -1
- package/dist/read.js +4 -4
- package/dist/read.js.map +1 -1
- package/dist/render.d.ts +3 -3
- package/dist/render.js +3 -3
- package/dist/session.d.ts +9 -9
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +10 -10
- package/dist/session.js.map +1 -1
- package/dist/validate.d.ts +8 -8
- package/dist/validate.d.ts.map +1 -1
- package/dist/validate.js +34 -37
- package/dist/validate.js.map +1 -1
- package/dist/vocabulary.js +2 -2
- package/dist/vocabulary.js.map +1 -1
- package/package.json +6 -6
- package/assets/base/08eaab3e1a6215d78283b82a94a0228367ac7bd78d0a746c56db79c8d7546c3a.ia.tgz +0 -0
- package/assets/host/d7722e32fd0511df2a6dfdf2353e621fdff1cf559d5c8b7ac256c7eceac0452f.tgz +0 -0
package/dist/init.js
CHANGED
|
@@ -1,59 +1,59 @@
|
|
|
1
1
|
import { registryWorkspace } from './adopt.js';
|
|
2
|
+
import { HostPluginError, lowerPlugin, readPlugin } from '@inventarch/workspace-runtime/internal/host-plugin';
|
|
2
3
|
import { adoptedBindings } from '@inventarch/db';
|
|
3
4
|
import { adoptionId, planAdoption, applyAdoption } from '@inventarch/distribution/registry';
|
|
4
5
|
import { readBase, PIN_PATH, PACKAGE_ID, DAMAGED } from './bundled-base.js';
|
|
6
|
+
import { canonical } from './plugin-sources.js';
|
|
5
7
|
export { readBase, PIN_PATH, baseArchivePath, PACKAGE_ID } from './bundled-base.js';
|
|
6
8
|
/**
|
|
7
9
|
* `ia init`: docs/specs/consumer-cli-contract/README.md §2.1, implementing
|
|
8
|
-
* docs/specs/workspace-initialization-apply/README.md (
|
|
9
|
-
* docs/specs/workspace-initialization/README.md (
|
|
10
|
+
* docs/specs/workspace-initialization-apply/README.md (the apply spec) to reach the end state
|
|
11
|
+
* docs/specs/workspace-initialization/README.md (the initialization spec) fixes.
|
|
10
12
|
*
|
|
11
|
-
* Without `--apply` it prints the reviewable plan: the owned paths, the target's classification (
|
|
12
|
-
* conflicts detected now, the starter it would write, the bundled base pin and the steps. It exits 0 whether or not
|
|
13
|
+
* Without `--apply` it prints the reviewable plan: the owned paths, the target's classification (the apply spec §1),
|
|
14
|
+
* the conflicts detected now, the starter it would write, the bundled base pin and the steps. It exits 0 whether or not
|
|
13
15
|
* conflicts were found, because reporting them is the command's job.
|
|
14
16
|
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
* descriptor names no distribution, so `ia pack` refuses until one is authored.
|
|
17
|
+
* SPEC `init`: the starter is three authored records in `.ia/src/workspace.ia` — the `@workspace`, its participant
|
|
18
|
+
* `@agent` and that participant's `@mandate` — and a create-only `.ia/.gitignore`. No local `@system` and no
|
|
19
|
+
* `@distribution` are written unless `--system` asks for them, inside `.ia/src/systems/<name>/`, where the packer
|
|
20
|
+
* finds a release's records; without them the release descriptor names no distribution, so `ia pack` refuses until
|
|
21
|
+
* one is authored.
|
|
21
22
|
*
|
|
22
|
-
* With `--apply` it runs the steps in order — verify the pin, install the bundled base unless it is already
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
* request. `<directory>` is the only way to name the target: this verb never performs root discovery, and `--root`
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
23
|
+
* With `--apply` it runs the steps in order — verify the pin, install the bundled base unless it is already installed
|
|
24
|
+
* as planned, author the starter create-only, admit and read the authored identities from the compiled graph, write
|
|
25
|
+
* `.ia/release.json`, the completion point — through the shared install services and `createFile`. No journal is
|
|
26
|
+
* written: a rerun derives from the workspace which steps are done (the apply spec §5). No step performs a network
|
|
27
|
+
* request. `<directory>` is the only way to name the target: this verb never performs root discovery, and `--root` is
|
|
28
|
+
* refused by the grammar rather than silently ignored. Two effects follow the completion point and are reported apart:
|
|
29
|
+
* the capture, through db's `writeCapture` as `ia capture` writes it, and, only with `--host`, the projection. A later
|
|
30
|
+
* step that fails leaves every earlier result in place and says so, naming its own command.
|
|
30
31
|
*
|
|
31
32
|
* `--host claude` or `--host codex` (docs/specs/host-registration/README.md §4 "init --host") is the project effect:
|
|
32
33
|
* once the workspace is initialized, after the capture, the `ia host <host> --apply` path runs under the question
|
|
33
|
-
* already answered here, so it never asks a second one, and its projection is written by `applyHostProjection`, the
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
34
|
+
* already answered here, so it never asks a second one, and its projection is written by `applyHostProjection`, the one
|
|
35
|
+
* writer of projection files. It reads the live revision rather than the capture, so a capture that fails does not keep
|
|
36
|
+
* it from running; the capture's refusal then says the projection is written. The plan names that step and writes
|
|
37
|
+
* nothing for it — the host plan needs `.ia/release.json`, which only the apply writes. A host step that refuses leaves
|
|
38
|
+
* the workspace initialized: the refusal keeps the service's code, message and location, and its next action names the
|
|
39
|
+
* rerun.
|
|
39
40
|
*
|
|
40
|
-
* `--migrate`
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
* distribution
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
* files (`collectMigration`, `applyMigration`).
|
|
41
|
+
* `--migrate` takes a workspace a 1.1.0 `ia init` wrote instead: one local system folder, `.ia/src/systems/<name>/`,
|
|
42
|
+
* whose `system.ia` holds exactly the starter `@system <name>`, registering no word, and `@agent <name>-steward`, and
|
|
43
|
+
* whose `records/workspace.ia` holds exactly `@workspace <name>` and `@distribution <name>-distribution`. It rewrites
|
|
44
|
+
* it into the three starter records: each other record file moves from the folder's `records/` to `.ia/src/`, where a
|
|
45
|
+
* record's word, not its folder, decides its system, so its identity is unchanged; the local system folder goes and the
|
|
46
|
+
* descriptor names no distribution, unless `--system` keeps the `@system` and its steward and re-roots the
|
|
47
|
+
* `@distribution` at the system. It plans by default, and plan and apply alike refuse a workspace of any other shape
|
|
48
|
+
* before anything is written. The three records use fields only the base this CLI bundles declares, so the apply first
|
|
49
|
+
* installs that base where the workspace has another, as `ia init` installs it; it then captures and re-projects each
|
|
50
|
+
* host whose projection the workspace owns through `applyHostProjection`, which retires the 1.x steward guard and
|
|
51
|
+
* deletes the owned steward agent files (`collectMigration`, `applyMigration`).
|
|
52
52
|
*/
|
|
53
53
|
import { readMigrationJournal, beginMigrationJournal, applyMigrationFiles, finishMigrationJournal, completeMigrationProjection, reopenMigrationProjection, } from './migration-journal.js';
|
|
54
54
|
import { spawnSync } from 'node:child_process';
|
|
55
55
|
import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, unlinkSync, } from 'node:fs';
|
|
56
|
-
import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
|
|
56
|
+
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
|
|
57
57
|
import { inertCommandRoot } from '@inventarch/runtime';
|
|
58
58
|
import { decodeReleaseDescriptor, deriveGenerationInputs, generationDigest, installationWorkspace, readExpandedBundle, DISTRIBUTION_ENGINE_VERSION, INSTALL_PATHS, sha256, } from '@inventarch/db/distribution';
|
|
59
59
|
import { verifyArchive } from '@inventarch/distribution/archive';
|
|
@@ -75,8 +75,9 @@ import { findProgram, programEnv, programHome } from './program.js';
|
|
|
75
75
|
import { codeOf, openSession } from './session.js';
|
|
76
76
|
import { atom, blockSymbolWidth, document, entry, fieldRows, headerLine, quote, safeRootAdvice, sectionLabel, truncateDigest, words, } from './render.js';
|
|
77
77
|
/**
|
|
78
|
-
* Relative to the `@inventarch/cli` package root, as `assets/vocabulary.json` is (vocabulary.ts CATALOGUE_PATH). The
|
|
79
|
-
* package's id is read from this pin and appears nowhere in this source:
|
|
78
|
+
* Relative to the `@inventarch/cli` package root, as `assets/vocabulary.json` is (vocabulary.ts CATALOGUE_PATH). The
|
|
79
|
+
* base package's id is read from this pin and appears nowhere in this source: the pin is the only authority for those
|
|
80
|
+
* bytes.
|
|
80
81
|
*/
|
|
81
82
|
export const DESCRIPTOR_PATH = '.ia/release.json';
|
|
82
83
|
export const STARTER_VERSION = '0.1.0';
|
|
@@ -84,10 +85,10 @@ export const STARTER_VERSION = '0.1.0';
|
|
|
84
85
|
export const INSTALL_LOCK = '.ia/distributions/install-lock.json';
|
|
85
86
|
const cachePath = (digest) => `.ia/distributions/cache/${digest}.ia.tgz`;
|
|
86
87
|
const systemFolder = (name) => `.ia/src/systems/${name}`;
|
|
87
|
-
/**
|
|
88
|
+
/** Where `ia author system <name>` writes a local system, as `ia init --system` does. */
|
|
88
89
|
export const systemPath = (name) => `${systemFolder(name)}/system.ia`;
|
|
89
90
|
const distributionPath = (name) => `${systemFolder(name)}/records/distribution.ia`;
|
|
90
|
-
/**
|
|
91
|
+
/** SPEC `init`: the one file the three starter records share, at the root of the authored source. */
|
|
91
92
|
export const WORKSPACE_PATH = '.ia/src/workspace.ia';
|
|
92
93
|
/** Create-only: the local working state each clone makes for itself, never the authored records or the lock. */
|
|
93
94
|
export const IGNORE_PATH = '.ia/.gitignore';
|
|
@@ -209,10 +210,10 @@ const NAME = /^[a-z][a-z0-9-]*$/;
|
|
|
209
210
|
const NAME_LIMIT = 64;
|
|
210
211
|
/** A local system name `ia init --system` and `ia author system` accept: the id rule and the system-name ceiling. */
|
|
211
212
|
export const isSystemName = (name) => NAME.test(name) && name.length <= NAME_LIMIT;
|
|
212
|
-
/**
|
|
213
|
+
/** `createFile`'s temporary name, `<target>.<randomUUID()>.tmp` (apps/distribution/src/files.ts:76). */
|
|
213
214
|
export const LEFTOVER = /^(system\.ia|workspace\.ia|distribution\.ia|release\.json|\.gitignore)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/;
|
|
214
215
|
/** The installation, not the target, is at fault; `ia doctor` names the channel a reinstall goes through. */
|
|
215
|
-
/**
|
|
216
|
+
/** The paths init owns: the authored source, the ignore file, the descriptor, the install state and the capture. */
|
|
216
217
|
export function ownedPaths(name, system = false) {
|
|
217
218
|
return [
|
|
218
219
|
{ path: '.ia/src/', purpose: 'authored records' },
|
|
@@ -226,7 +227,7 @@ export function ownedPaths(name, system = false) {
|
|
|
226
227
|
}
|
|
227
228
|
/**
|
|
228
229
|
* §2.1: an existing directory, or a single new segment under an existing directory. Anything else is usage. `rerun`
|
|
229
|
-
* spells the refused invocation for another target
|
|
230
|
+
* spells the refused invocation for another target; `runInit` keeps every other argument it was given.
|
|
230
231
|
*/
|
|
231
232
|
export function resolveTarget(cwd, supplied, rerun = (target) => `ia init ${quote(target)}`) {
|
|
232
233
|
const target = supplied === undefined ? resolve(cwd) : isAbsolute(supplied) ? resolve(supplied) : resolve(cwd, supplied);
|
|
@@ -252,12 +253,12 @@ const writable = (path) => {
|
|
|
252
253
|
}
|
|
253
254
|
};
|
|
254
255
|
/**
|
|
255
|
-
*
|
|
256
|
-
*
|
|
257
|
-
*
|
|
258
|
-
*
|
|
256
|
+
* Read the pin and verify the bytes against it, never falling back to another file. A missing archive is read as no
|
|
257
|
+
* bytes, so the archive verifier's own refusal reports it; a pin that cannot be read at all has no digest to verify
|
|
258
|
+
* against and is the CLI's own failure. Either way the next action says the installation is damaged, because nothing
|
|
259
|
+
* the user did to the target can cause it.
|
|
259
260
|
*/
|
|
260
|
-
/**
|
|
261
|
+
/** The name's normalization: lowercase, every run outside `[a-z0-9-]` becomes `-`, no leading or trailing `-`. */
|
|
261
262
|
export const normalizeName = (directory) => {
|
|
262
263
|
const normalized = directory.toLowerCase().replace(/[^a-z0-9-]+/g, '-');
|
|
263
264
|
let start = 0, end = normalized.length;
|
|
@@ -268,7 +269,7 @@ export const normalizeName = (directory) => {
|
|
|
268
269
|
end--;
|
|
269
270
|
return normalized.slice(start, end);
|
|
270
271
|
};
|
|
271
|
-
/**
|
|
272
|
+
/** Valid only if the name, the full id and the public-system rule all hold. Nothing is invented. */
|
|
272
273
|
export function starterIdentity(root, supplied, systems) {
|
|
273
274
|
const name = supplied === undefined ? normalizeName(basename(root)) : supplied.slice(supplied.indexOf('/') + 1);
|
|
274
275
|
const id = supplied ?? `local/${name}`;
|
|
@@ -283,10 +284,9 @@ export function starterIdentity(root, supplied, systems) {
|
|
|
283
284
|
return { name, id, conflict: null };
|
|
284
285
|
}
|
|
285
286
|
/**
|
|
286
|
-
* `--system`'s local system, the 1.x starter system unchanged (
|
|
287
|
-
*
|
|
288
|
-
*
|
|
289
|
-
* requires (operator decision, 2026-09-25).
|
|
287
|
+
* `--system`'s local system, the 1.x starter system unchanged (verbatim in shape): the steward needs `agent-system`,
|
|
288
|
+
* and `governance` is required. `work-system` is required so the system folder can hold `@plan`, `@milestone`, `@task`
|
|
289
|
+
* and `@decision` records with no edit: a system may use only words owned by systems it directly requires.
|
|
290
290
|
*/
|
|
291
291
|
export function starterSystem(name) {
|
|
292
292
|
return [
|
|
@@ -312,11 +312,11 @@ export function starterSystem(name) {
|
|
|
312
312
|
].join('\n');
|
|
313
313
|
}
|
|
314
314
|
/**
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
*
|
|
318
|
-
*
|
|
319
|
-
*
|
|
315
|
+
* SPEC `init`'s three records, at placement authored (band 100), with only the fields their schemas declare. The
|
|
316
|
+
* `@workspace` composes every installed system, so nothing installed is unreachable, declares the authored root its
|
|
317
|
+
* records are captured under and names the participant as its steward. The participant `@agent` implies no host
|
|
318
|
+
* permission, and its `@mandate` grants it closed moves over that workspace; the mandate's one prose clause claims
|
|
319
|
+
* nothing. Every name is the workspace's.
|
|
320
320
|
*/
|
|
321
321
|
export function starterRecords(name, systems, sources = []) {
|
|
322
322
|
return [
|
|
@@ -352,7 +352,7 @@ export function starterRecords(name, systems, sources = []) {
|
|
|
352
352
|
].join('\n');
|
|
353
353
|
}
|
|
354
354
|
/**
|
|
355
|
-
* `--system`'s release root (
|
|
355
|
+
* `--system`'s release root (a distribution's roots are system registrations). It
|
|
356
356
|
* sits in the system folder, so the closure from it stays inside folders the packer can release
|
|
357
357
|
* (apps/distribution/src/snapshot.ts, "Release roots must belong to native system folders").
|
|
358
358
|
*/
|
|
@@ -371,8 +371,8 @@ export function starterDistribution(name) {
|
|
|
371
371
|
}
|
|
372
372
|
/**
|
|
373
373
|
* The authored files in the order the author step writes them, and the records they hold, in file order. With
|
|
374
|
-
* `--system` the `@workspace` composes the local system after `systems` (
|
|
375
|
-
*
|
|
374
|
+
* `--system` the `@workspace` composes the local system after `systems` (a repository that owns vocabulary composes
|
|
375
|
+
* its own system), so the packet renders a pointer line for it.
|
|
376
376
|
*/
|
|
377
377
|
export function starterFiles(name, systems, system, sources = []) {
|
|
378
378
|
return {
|
|
@@ -437,10 +437,10 @@ const canonicalHttps = (value) => {
|
|
|
437
437
|
};
|
|
438
438
|
const LOCAL = { repository: null, commit: null, recipe: 'ustar-v1', epoch: 0 };
|
|
439
439
|
/**
|
|
440
|
-
*
|
|
441
|
-
* first remote Git lists. The remote's configured URL is read as written, so an SSH remote is "no
|
|
442
|
-
* is never rewritten into a guessed HTTPS one; a URL carrying credentials is refused the same way
|
|
443
|
-
* into a file meant to be committed.
|
|
440
|
+
* The descriptor's provenance. Sourced only from a Git checkout with a commit and an HTTPS remote: `origin` when it
|
|
441
|
+
* exists, else the first remote Git lists. The remote's configured URL is read as written, so an SSH remote is "no
|
|
442
|
+
* HTTPS remote" and is never rewritten into a guessed HTTPS one; a URL carrying credentials is refused the same way
|
|
443
|
+
* rather than copied into a file meant to be committed.
|
|
444
444
|
*/
|
|
445
445
|
export function readProvenance(git) {
|
|
446
446
|
const local = (missing) => ({ source: LOCAL, missing });
|
|
@@ -479,10 +479,10 @@ const baseDependencies = (base) => [
|
|
|
479
479
|
{ id: base.pin.id, range: `^${base.pin.version}`, systems: base.systems },
|
|
480
480
|
];
|
|
481
481
|
/**
|
|
482
|
-
*
|
|
483
|
-
* without it, `undefined` leaves the key out, because a default starter authors no `@distribution
|
|
482
|
+
* The release descriptor init writes. With `--system`, `distribution` stays null until admission reads the compiled
|
|
483
|
+
* record; without it, `undefined` leaves the key out, because a default starter authors no `@distribution`.
|
|
484
484
|
*/
|
|
485
|
-
export function starterDescriptor(id, name, base, provenance, distribution) {
|
|
485
|
+
export function starterDescriptor(id, name, base, provenance, distribution, assets = []) {
|
|
486
486
|
return {
|
|
487
487
|
formatVersion: 1,
|
|
488
488
|
id,
|
|
@@ -491,7 +491,7 @@ export function starterDescriptor(id, name, base, provenance, distribution) {
|
|
|
491
491
|
engine: `^${DISTRIBUTION_ENGINE_VERSION}`,
|
|
492
492
|
language: ['1.0'],
|
|
493
493
|
dependencies: baseDependencies(base),
|
|
494
|
-
assets
|
|
494
|
+
assets,
|
|
495
495
|
license: 'UNLICENSED',
|
|
496
496
|
description: `The ${name} workspace.`,
|
|
497
497
|
source: provenance.source,
|
|
@@ -499,7 +499,7 @@ export function starterDescriptor(id, name, base, provenance, distribution) {
|
|
|
499
499
|
}
|
|
500
500
|
/** Two-space JSON with a final newline; `decodeReleaseDescriptor` requires the dependency rows sorted, as they are. */
|
|
501
501
|
export const descriptorText = (descriptor) => JSON.stringify(descriptor, null, 2) + '\n';
|
|
502
|
-
/**
|
|
502
|
+
/** Exactly the one request and the one package the pin describes. */
|
|
503
503
|
export const locksBase = (lock, pin) => lock !== undefined &&
|
|
504
504
|
lock.requests.length === 1 &&
|
|
505
505
|
lock.requests[0].id === pin.id &&
|
|
@@ -528,9 +528,42 @@ function filesBelow(root, path) {
|
|
|
528
528
|
walk(path);
|
|
529
529
|
return found;
|
|
530
530
|
}
|
|
531
|
+
/** Whether `path` is `base` or lies below it; an in-base name that only begins with `..`, such as `..x`, is below it. */
|
|
532
|
+
const within = (base, path) => {
|
|
533
|
+
const here = relative(base, path);
|
|
534
|
+
return here === '' || (here !== '..' && !here.startsWith(`..${sep}`) && !isAbsolute(here));
|
|
535
|
+
};
|
|
531
536
|
/**
|
|
532
|
-
*
|
|
533
|
-
*
|
|
537
|
+
* `--from`: lower the plugin; any unresolved construct refuses before anything is planned or written, with every entry
|
|
538
|
+
* in the refusal's details. A target that is the plugin directory or lies inside it is refused before the plugin is
|
|
539
|
+
* read, since lowering would write into its own source; a target that contains the plugin is legal.
|
|
540
|
+
*/
|
|
541
|
+
function lowerFrom(from, root, name, lower) {
|
|
542
|
+
const plugin = resolve(from);
|
|
543
|
+
let plan = null;
|
|
544
|
+
try {
|
|
545
|
+
// The plugin is always read, so an input error refuses at once; lowering needs a name and a target free of conflicts.
|
|
546
|
+
if (statSync(plugin, { throwIfNoEntry: false })?.isDirectory() !== true)
|
|
547
|
+
throw new HostPluginError('IA-PLUGIN-INPUT', `${from} is not a plugin directory`);
|
|
548
|
+
if (within(canonical(plugin), canonical(root)))
|
|
549
|
+
throw new Refusal('IA-PLUGIN-INPUT', `${root} is the plugin directory or lies inside it; lowering never writes into its own source`, 1, { path: plugin }, `Choose a target directory outside the plugin, then run "ia init <directory> --from ${quote(plugin)}".`);
|
|
550
|
+
const inventory = readPlugin(plugin);
|
|
551
|
+
if (lower && name !== null)
|
|
552
|
+
plan = lowerPlugin(inventory, name);
|
|
553
|
+
}
|
|
554
|
+
catch (error) {
|
|
555
|
+
if (error instanceof HostPluginError)
|
|
556
|
+
throw new Refusal(error.code, error.message, 1, { path: plugin }, 'Run "ia init --help" for what a plugin directory may hold.');
|
|
557
|
+
throw error;
|
|
558
|
+
}
|
|
559
|
+
if (plan !== null && plan.unresolved.length > 0)
|
|
560
|
+
throw new Refusal('IA-LOWER-UNRESOLVED', `${plan.unresolved.length} construct(s) cannot be lowered yet: ${plan.unresolved.slice(0, 20).join('; ')}${plan.unresolved.length > 20 ? '; ...' : ''}`, 1, { path: plugin }, 'Nothing was written; run "ia init --help" for what a plugin directory may hold.', null, undefined, plan.unresolved);
|
|
561
|
+
return plan;
|
|
562
|
+
}
|
|
563
|
+
/**
|
|
564
|
+
* The plan: the target's classification, its conflicts and the steps. The starter bytes compared are what this
|
|
565
|
+
* invocation would write for its resolved id: they depend only on the name, `--system` and the bundled manifest, so
|
|
566
|
+
* they are recomputed on every run instead of being journaled.
|
|
534
567
|
*/
|
|
535
568
|
export function collectInit(request) {
|
|
536
569
|
const { root, host } = request;
|
|
@@ -552,8 +585,28 @@ export function collectInit(request) {
|
|
|
552
585
|
if (!sources.includes(source))
|
|
553
586
|
sources.push(source);
|
|
554
587
|
}
|
|
555
|
-
|
|
556
|
-
|
|
588
|
+
// An initialized target keeps init's own conflict report; only a target free of conflicts is lowered.
|
|
589
|
+
const lowered = request.from === undefined
|
|
590
|
+
? null
|
|
591
|
+
: lowerFrom(request.from, root, name, identity.conflict === null && !existsSync(resolve(root, DESCRIPTOR_PATH)));
|
|
592
|
+
const { files, records } = name === null
|
|
593
|
+
? { files: [], records: [] }
|
|
594
|
+
: lowered !== null
|
|
595
|
+
? {
|
|
596
|
+
files: [
|
|
597
|
+
{ path: WORKSPACE_PATH, text: starterRecords(name, [...base.systems, name], sources) },
|
|
598
|
+
...lowered.files.map((file) => ({ path: file.path, text: file.bytes.toString('utf8') })),
|
|
599
|
+
],
|
|
600
|
+
records: [
|
|
601
|
+
{ word: 'workspace', name, path: WORKSPACE_PATH },
|
|
602
|
+
{ word: 'agent', name, path: WORKSPACE_PATH },
|
|
603
|
+
{ word: 'mandate', name: `${name}-mandate`, path: WORKSPACE_PATH },
|
|
604
|
+
...lowered.records,
|
|
605
|
+
],
|
|
606
|
+
}
|
|
607
|
+
: starterFiles(name, base.systems, system, sources);
|
|
608
|
+
const assets = lowered?.assets ?? [];
|
|
609
|
+
// A temporary file `createFile` left beside one of this initialization's own targets.
|
|
557
610
|
const targets = new Set([...files.map((file) => file.path), IGNORE_PATH, DESCRIPTOR_PATH]);
|
|
558
611
|
// `.<uuid>.tmp` is 41 characters: the dot, a 36-character UUID and `.tmp`.
|
|
559
612
|
const leftover = (path) => LEFTOVER.test(basename(path)) && targets.has(path.slice(0, -41));
|
|
@@ -561,11 +614,11 @@ export function collectInit(request) {
|
|
|
561
614
|
const written = new Set();
|
|
562
615
|
let lock = false, installed = false;
|
|
563
616
|
if (present) {
|
|
564
|
-
// readInstalledState refuses while `.ia/distributions/pending.json` exists, which is
|
|
565
|
-
//
|
|
566
|
-
//
|
|
617
|
+
// readInstalledState refuses while `.ia/distributions/pending.json` exists, which is recovery-required: an
|
|
618
|
+
// interrupted apply must be recovered before anything reasons about this workspace. Its rows are held back so the
|
|
619
|
+
// plan lists authored source, then the lock, then install state, as before.
|
|
567
620
|
const installation = [];
|
|
568
|
-
//
|
|
621
|
+
// A held or abandoned install lock is recovery-required too. A process killed inside
|
|
569
622
|
// applyInstallation skips the `finally` that releases it (apps/distribution/src/install.ts:67-97), before
|
|
570
623
|
// `pending` exists and after it is removed. `ia recover installation` clears a dead holder's lock and refuses a
|
|
571
624
|
// live one (`acquire(root, true)`, install.ts:71), so it is the remedy whether or not a journal exists; the
|
|
@@ -624,7 +677,7 @@ export function collectInit(request) {
|
|
|
624
677
|
reason: 'A lock already names direct requests and resolved versions',
|
|
625
678
|
});
|
|
626
679
|
conflicts.push(...installation);
|
|
627
|
-
//
|
|
680
|
+
// A completed initialization is a conflict, because the starter now belongs to the user (band 100).
|
|
628
681
|
if (existsSync(resolve(root, DESCRIPTOR_PATH)))
|
|
629
682
|
conflicts.push({ path: DESCRIPTOR_PATH, reason: 'The target is already initialized' });
|
|
630
683
|
}
|
|
@@ -665,7 +718,10 @@ export function collectInit(request) {
|
|
|
665
718
|
system,
|
|
666
719
|
files,
|
|
667
720
|
records,
|
|
668
|
-
|
|
721
|
+
assets,
|
|
722
|
+
descriptor: id === null || name === null
|
|
723
|
+
? null
|
|
724
|
+
: starterDescriptor(id, name, base, provenance, system ? null : undefined, assets),
|
|
669
725
|
base: base.pin,
|
|
670
726
|
systems: base.systems,
|
|
671
727
|
provenance,
|
|
@@ -679,20 +735,20 @@ export function collectInit(request) {
|
|
|
679
735
|
/**
|
|
680
736
|
* The sentence the next action of a step that fails or is interrupted once the descriptor is written opens with:
|
|
681
737
|
* initialization is complete, so running `ia init` again refuses the target, and each effect is finished by its own
|
|
682
|
-
* command
|
|
738
|
+
* command. The project effect's also says whether the capture before it was taken.
|
|
683
739
|
*/
|
|
684
740
|
const INITIALIZED = 'The workspace is initialized.';
|
|
685
741
|
const CAPTURED = 'The workspace is initialized and captured.';
|
|
686
742
|
const UNCAPTURED = 'The workspace is initialized but not captured.';
|
|
687
743
|
/**
|
|
688
|
-
*
|
|
689
|
-
*
|
|
690
|
-
*
|
|
691
|
-
*
|
|
692
|
-
*
|
|
744
|
+
* The apply's steps, in SPEC `init`'s order. Each step before the descriptor either completes or leaves a state
|
|
745
|
+
* `collectInit` classifies as resumable or recovery-required. The signal is observed at step boundaries (§5): before
|
|
746
|
+
* the first write it is the plain interruption and the target is byte-identical; after one, the interruption names the
|
|
747
|
+
* rerun that finishes. Two effects follow the completion point, each reported apart, and each that fails or is
|
|
748
|
+
* interrupted leaves the workspace initialized and names its own command: the capture, `ia capture`, and, only when
|
|
693
749
|
* `options.project` is given (`--host`), the project effect, `ia host`. The project effect reads the live revision,
|
|
694
|
-
* never the capture
|
|
695
|
-
*
|
|
750
|
+
* never the capture, so it runs after a capture that failed too, and that failure is then refused with the capture's
|
|
751
|
+
* own repair, after a sentence saying the projection is written.
|
|
696
752
|
*/
|
|
697
753
|
export async function applyInit(view, options) {
|
|
698
754
|
const { root, starter } = view;
|
|
@@ -733,12 +789,12 @@ export async function applyInit(view, options) {
|
|
|
733
789
|
if (ignore === 'written')
|
|
734
790
|
createFile(root, IGNORE_PATH, Buffer.from(IGNORE_TEXT));
|
|
735
791
|
boundary('author');
|
|
736
|
-
// Step 5, admission: the identities are read from the compiled graph, never string-constructed
|
|
792
|
+
// Step 5, admission: the identities are read from the compiled graph, never string-constructed.
|
|
737
793
|
const { compiled } = admitStarter(root, starter.records, 'initialized', '');
|
|
738
794
|
const authored = compiled.map((record) => record.identity), distribution = compiled.find((record) => record.discriminator === 'distribution')?.identity ?? null;
|
|
739
795
|
boundary('admission');
|
|
740
|
-
// Step 6, the completion point (§
|
|
741
|
-
createFile(root, DESCRIPTOR_PATH, Buffer.from(descriptorText(starterDescriptor(id, name, base, starter.provenance, distribution ?? undefined))));
|
|
796
|
+
// Step 6, the completion point (the apply spec §5). A default starter's descriptor names no distribution.
|
|
797
|
+
createFile(root, DESCRIPTOR_PATH, Buffer.from(descriptorText(starterDescriptor(id, name, base, starter.provenance, distribution ?? undefined, starter.assets))));
|
|
742
798
|
checkpoint('init:descriptor');
|
|
743
799
|
const installed = readInstalledState({ root });
|
|
744
800
|
// Step 7, the capture effect: `ia capture` on the workspace just initialized, written through db's writeCapture. A
|
|
@@ -780,8 +836,8 @@ export async function applyInit(view, options) {
|
|
|
780
836
|
};
|
|
781
837
|
}
|
|
782
838
|
/**
|
|
783
|
-
*
|
|
784
|
-
* is cached, resolved from that one archive and installed as the workspace's one request, by `ia init` into a new
|
|
839
|
+
* The installer's three calls, offline, resolved the way `ia install` resolves (distribute.ts collectPlan): the bundled
|
|
840
|
+
* base is cached, resolved from that one archive and installed as the workspace's one request, by `ia init` into a new
|
|
785
841
|
* workspace and by `ia init --migrate` in place of a 1.x base. A signal during it is `resume`.
|
|
786
842
|
*/
|
|
787
843
|
async function installBase(root, base, operation, options, resume) {
|
|
@@ -812,7 +868,7 @@ async function installBase(root, base, operation, options, resume) {
|
|
|
812
868
|
const conflictMessage = (conflicts, blocked) => conflicts.length === 1
|
|
813
869
|
? `${conflicts[0].reason}: ${conflicts[0].path}`
|
|
814
870
|
: `${conflicts.length} conflicts block ${blocked}: ${conflicts.map((row) => `${row.path} (${row.reason})`).join('; ')}`;
|
|
815
|
-
/**
|
|
871
|
+
/** Every conflict is listed; `--apply` refuses at class 3 and writes nothing. */
|
|
816
872
|
function initializedNext(view) {
|
|
817
873
|
if (!view.conflicts.some((row) => row.path === DESCRIPTOR_PATH && row.reason === 'The target is already initialized'))
|
|
818
874
|
return null;
|
|
@@ -907,7 +963,7 @@ const stepRows = (view, symbol, caps) => [
|
|
|
907
963
|
const provenanceText = (provenance) => provenance.missing === null
|
|
908
964
|
? `${provenance.source.repository} at ${provenance.source.commit.slice(0, 12)}`
|
|
909
965
|
: `Unpublished local; ${MISSING[provenance.missing]}`;
|
|
910
|
-
/**
|
|
966
|
+
/** The starter rows name the records, release and provenance this initialization would write. */
|
|
911
967
|
const starterRows = (view, caps) => {
|
|
912
968
|
const { starter } = view, pin = starter.base;
|
|
913
969
|
const rows = starter.name === null || starter.id === null
|
|
@@ -1047,7 +1103,7 @@ export function renderApplied(view, applied, caps) {
|
|
|
1047
1103
|
words(`${applied.resumed ? 'Finished initializing' : 'Initialized'} ${applied.id}; release descriptor ${DESCRIPTOR_PATH}.`),
|
|
1048
1104
|
words(`Installed generation ${truncateDigest(applied.generation, caps.ascii)}, counter ${applied.counter}.`),
|
|
1049
1105
|
], { depth: 1, symbol: 'success' }, caps),
|
|
1050
|
-
//
|
|
1106
|
+
// SPEC `init`: the records authored, then each effect, reported apart.
|
|
1051
1107
|
authoredEntry(applied, caps),
|
|
1052
1108
|
capturedEntry(applied.effects.capture, caps),
|
|
1053
1109
|
applied.effects.project === 'skipped'
|
|
@@ -1073,7 +1129,8 @@ function invocationOf(context) {
|
|
|
1073
1129
|
const { args } = context;
|
|
1074
1130
|
const parts = ['ia init', ...args.positionals.map(quote)];
|
|
1075
1131
|
const id = args.value('id'), host = args.value('host');
|
|
1076
|
-
|
|
1132
|
+
// `--from` too, as typed: without it the apply, resume and conflict commands would initialize a plain starter.
|
|
1133
|
+
for (const option of ['adopt', 'registry', 'from']) {
|
|
1077
1134
|
const value = args.value(option);
|
|
1078
1135
|
if (value !== undefined)
|
|
1079
1136
|
parts.push(`--${option}`, quote(value));
|
|
@@ -1101,8 +1158,8 @@ export async function runInit(context) {
|
|
|
1101
1158
|
return await initialize(context, root, id);
|
|
1102
1159
|
}
|
|
1103
1160
|
catch (error) {
|
|
1104
|
-
//
|
|
1105
|
-
//
|
|
1161
|
+
// This verb's target is `<directory>`, which `--root` cannot carry, so a service refusal with no remedy of its own
|
|
1162
|
+
// is given the fallback for that directory rather than for the cwd, which may not be it.
|
|
1106
1163
|
if (error instanceof Refusal || error instanceof Interrupted || error instanceof UsageError || host.signal?.aborted)
|
|
1107
1164
|
throw error;
|
|
1108
1165
|
throw refusalOf(error, { command: 'init', root });
|
|
@@ -1133,7 +1190,9 @@ async function initialize(context, root, id) {
|
|
|
1133
1190
|
root,
|
|
1134
1191
|
host: selected,
|
|
1135
1192
|
id,
|
|
1136
|
-
system: args.flag('system'),
|
|
1193
|
+
system: args.value('from') === undefined && args.flag('system'),
|
|
1194
|
+
// Read against the invocation's directory, as the target is, so `--from .` names the directory it was typed in.
|
|
1195
|
+
from: args.value('from') === undefined ? undefined : resolve(host.cwd, args.value('from')),
|
|
1137
1196
|
packageRoot: host.packageRoot,
|
|
1138
1197
|
git: gitIn(existing, host.env),
|
|
1139
1198
|
invocation: invocationOf(context),
|
|
@@ -1153,7 +1212,7 @@ async function initialize(context, root, id) {
|
|
|
1153
1212
|
// §2.8 rule 3, as `ia install` asks it: parsing already refused every `--apply` whose question cannot be answered.
|
|
1154
1213
|
if (!args.flag('yes') && !(await confirm(host.interaction, renderInitSummary(view, caps), CONFIRMATION)))
|
|
1155
1214
|
return { exitCode: 0, stdout: renderDeclined(view, caps, args.positionals[0], host), stderr: '' };
|
|
1156
|
-
// The project effect, last (
|
|
1215
|
+
// The project effect, last (SPEC `init`): the `ia host` path, whose apply writes the receipt.
|
|
1157
1216
|
const project = selected === 'none' ? undefined : (done) => registerHost(context, selected, root, done);
|
|
1158
1217
|
try {
|
|
1159
1218
|
return rendered(await applyInit(view, { packageRoot: host.packageRoot, signal: host.signal, project }));
|
|
@@ -1183,14 +1242,14 @@ function registerHost(context, selected, root, done) {
|
|
|
1183
1242
|
const host = `ia host ${selected} --root ${quote(root)} --apply`;
|
|
1184
1243
|
const finish = `Run "${host}" to finish host registration.`, recover = `Run "${host}" for the recovery it names, then run it again to finish host registration.`;
|
|
1185
1244
|
const composed = (next) => `${done} ${next === null ? finish : next.endsWith(THEN_RERUN) ? recover : rootedNext(next, selected, root)}`;
|
|
1186
|
-
//
|
|
1245
|
+
// A signal observed after the last init write interrupts a command that has written, so it names the rerun.
|
|
1187
1246
|
if (context.host.signal?.aborted)
|
|
1188
1247
|
throw new Interrupted(composed(null));
|
|
1189
1248
|
const command = findCommand('host');
|
|
1190
1249
|
const args = parseArguments([selected, '--root', root, '--apply', '--yes'], command.grammar);
|
|
1191
1250
|
try {
|
|
1192
1251
|
const applied = applyHostSet(collectHost({ ...context, command, args }), context.host.packageRoot, context.host.signal);
|
|
1193
|
-
// A host apply that returns has projected, and `applyHostProjection` wrote the receipt
|
|
1252
|
+
// A host apply that returns has projected, and `applyHostProjection` wrote the receipt before it returned.
|
|
1194
1253
|
const receipt = readReceipt(root, selected);
|
|
1195
1254
|
return { effect: { host: selected, files: receipt.files, receipt: STATE.receipt(selected) }, host: applied };
|
|
1196
1255
|
}
|
|
@@ -1444,7 +1503,7 @@ export function collectMigration(request) {
|
|
|
1444
1503
|
for (const host of projected)
|
|
1445
1504
|
try {
|
|
1446
1505
|
const guard = planRetirement(root, host) === null ? 'none' : 'retire';
|
|
1447
|
-
// The hook step the projection effect runs
|
|
1506
|
+
// The hook step the projection effect runs, found before the migration plans its writes.
|
|
1448
1507
|
preflightHooks(root, host);
|
|
1449
1508
|
hosts.push({ host, guard, files: migratedFiles(root, host) });
|
|
1450
1509
|
}
|
|
@@ -1540,7 +1599,7 @@ const MIGRATED_CAPTURED = 'The workspace is migrated and captured.';
|
|
|
1540
1599
|
const MIGRATED_UNCAPTURED = 'The workspace is migrated but not captured.';
|
|
1541
1600
|
/**
|
|
1542
1601
|
* The admission step `ia init` and `ia init --migrate` share: zero error findings, then each planned starter record as
|
|
1543
|
-
* the compiled graph holds it at its path, never string-constructed
|
|
1602
|
+
* the compiled graph holds it at its path, never string-constructed, with every record the graph holds.
|
|
1544
1603
|
* `done` opens each refusal's next action with what the command completed before it, if anything.
|
|
1545
1604
|
*/
|
|
1546
1605
|
function admitStarter(root, planned, what, done) {
|
|
@@ -1954,7 +2013,7 @@ async function migrate(context, root) {
|
|
|
1954
2013
|
/**
|
|
1955
2014
|
* A finished git run's answer, or null when git is not really there: it could not start, or it is the macOS stub
|
|
1956
2015
|
* `/usr/bin/git`, which only asks for the Xcode Command Line Tools and fails; reading that as "not a Git checkout" would
|
|
1957
|
-
* send the user after the wrong fix (#323).
|
|
2016
|
+
* send the user after the wrong fix (crowncodes/ia#323).
|
|
1958
2017
|
*/
|
|
1959
2018
|
export function gitAnswer(result) {
|
|
1960
2019
|
if (result.error !== undefined)
|