@astrale-os/sdk 0.6.0-beta.3 → 0.6.0-beta.30

package/dist/tooling/cli/diff/render.js

@@ -0,0 +1,131 @@
+/** What a change of each level is, in the [.105820] message. */
+const NATURE = Object.freeze({
+    major: 'breaking change',
+    minor: 'addition',
+    patch: 'change',
+});
+const LEVELS = ['patch', 'minor', 'major'];
+/**
+ * 0 when the declared version is accepted, already published (the report is then informational:
+ * a feature branch keeps the last published number until its release), or has nothing to compare
+ * with; 1 when an unpublished declared version is too low.
+ */
+export function diffExitCode(report) {
+    return report.published || report.accepted ? 0 : 1;
+}
+/**
+ * The report for a person. `summary` describes the comparison; `refusal` is the [.105820] message
+ * for an unpublished version that is too low (tech Versioning), printed as an error.
+ */
+export function renderDiff(report) {
+    const subject = `${report.origin} ${report.declared}`;
+    if (report.registry === 'unregistered') {
+        return {
+            summary: [
+                `${report.origin} is not in the Domain registry, or you may not read it: nothing to compare.`,
+            ],
+            refusal: [],
+        };
+    }
+    if (report.baseline === undefined) {
+        return {
+            summary: [
+                `${subject}: no stable version up to ${report.declared} is published, nothing to compare.`,
+            ],
+            refusal: [],
+        };
+    }
+    const level = report.level;
+    const required = `at least ${report.next} (${NATURE[level]})`;
+    const rows = changeRows(report.changes, report.origin);
+    if (report.changes.length === 0) {
+        const state = report.published ? 'is published' : 'is accepted';
+        return {
+            summary: [`${subject} ${state}: no change since ${report.baseline}.`],
+            refusal: [],
+        };
+    }
+    if (report.published) {
+        return {
+            summary: [
+                `${subject} is published. The changes since ${report.baseline} need ${required}:`,
+                ...rows,
+            ],
+            refusal: [],
+        };
+    }
+    if (report.accepted) {
+        return {
+            summary: [
+                `${subject} is accepted. The changes since ${report.baseline} need ${required}:`,
+                ...rows,
+            ],
+            refusal: [],
+        };
+    }
+    // Only the changes that set the level are listed, as [.105820] lists the breaking ones.
+    const binding = report.changes.filter((change) => change.bump === level);
+    const others = report.changes.length - binding.length;
+    const declare = report.suggestion ?? report.next;
+    return {
+        summary: [],
+        refusal: [
+            `error: ${report.declared} is too low, ${NATURE[level]} since ${report.baseline}: at least ${report.next} is required`,
+            ...changeRows(binding, report.origin),
+            ...(others === 0 ? [] : [`  (and ${others} other ${others === 1 ? 'change' : 'changes'})`]),
+            level === 'major'
+                ? `Declare ${declare}, or keep the old member (expand then contract).`
+                : `Declare ${declare}.`,
+        ],
+    };
+}
+/**
+ * One line per changed member, `<kind> <name> <states> (<details>)`, in report order. A member the
+ * engine observes through several facets (a removed Method loses its existence and its signature)
+ * is one line.
+ */
+function changeRows(changes, origin) {
+    const members = new Map();
+    for (const change of changes) {
+        const key = `${change.facet === 'build' || change.facet === 'schema' ? change.facet : ''}\u0000${change.subject}`;
+        const member = members.get(key) ?? {
+            ...memberName(change, origin),
+            states: [],
+            details: [],
+            bump: 'patch',
+        };
+        if (!member.states.includes(change.state))
+            member.states.push(change.state);
+        if (change.detail !== undefined && !member.details.includes(change.detail)) {
+            member.details.push(change.detail);
+        }
+        if (LEVELS.indexOf(change.bump) > LEVELS.indexOf(member.bump))
+            member.bump = change.bump;
+        members.set(key, member);
+    }
+    const rows = [...members.values()];
+    const kindWidth = Math.max(0, ...rows.map(({ kind }) => kind.length)) + 1;
+    const nameWidth = Math.max(0, ...rows.map(({ name }) => name.length)) + 3;
+    return rows.map(({ kind, name, states, details }) => `  ${kind.padEnd(kindWidth)}${name.padEnd(nameWidth)}${states.join(', ')}${details.length === 0 ? '' : ` (${details.join('; ')})`}`);
+}
+/**
+ * `class.Project.method.archive` reads `method Project.archive`. A Key of another origin keeps
+ * its origin; a whole-Domain change names the origin.
+ */
+function memberName(change, origin) {
+    if (change.facet === 'build' || change.facet === 'schema') {
+        return { kind: change.facet, name: change.subject };
+    }
+    const separator = change.subject.indexOf(':');
+    const local = change.subject.slice(separator + 1);
+    const prefix = separator > 0 && change.subject.slice(0, separator) !== origin
+        ? `${change.subject.slice(0, separator)}:`
+        : '';
+    const member = /^class\.([^.]+)\.(property|method)\.(.+)$/u.exec(local);
+    if (member !== null)
+        return { kind: member[2], name: `${prefix}${member[1]}.${member[3]}` };
+    const dot = local.indexOf('.');
+    return dot > 0
+        ? { kind: local.slice(0, dot), name: `${prefix}${local.slice(dot + 1)}` }
+        : { kind: 'member', name: change.subject };
+}

package/dist/tooling/cli/diff/report.d.ts

@@ -0,0 +1,88 @@
+import type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
+import type { BumpLevel, Version } from '../../../platform/versioning/index.js';
+import type { RegistryIndex, RegistryPublication } from '../registry/index.js';
+/** One change since the baseline, with the level it alone requires. */
+export interface DiffChangeV1 {
+    /**
+     * The compared member's Key (`issues.astrale.ai:class.Issue.property.priority`), or the Domain's
+     * origin for a change of the whole build or Schema.
+     */
+    readonly subject: string;
+    /**
+     * The compatibility engine's facet (`method.existence`, `property.required`, …), `schema` for a
+     * new Schema revision of equivalent meaning, `build` for new code under the same revision.
+     */
+    readonly facet: string;
+    readonly state: 'missing' | 'changed' | 'added';
+    readonly bump: BumpLevel;
+    /** What differs, such as `optional → required`, when the observation says. */
+    readonly detail?: string;
+}
+/**
+ * `astrale-domain diff --json` on stdout: the version the Project declares, checked against the
+ * highest published stable version up to it (CT30).
+ */
+export interface DiffReportV1 {
+    readonly format: 'astrale.diff-report';
+    readonly version: 1;
+    readonly origin: string;
+    /** `package.json` `version`. */
+    readonly declared: string;
+    /** The declared version already names a Publication: the report is informational. */
+    readonly published: boolean;
+    /** `unregistered`: no Domain of this origin the caller may read; nothing is compared. */
+    readonly registry: 'read' | 'unregistered';
+    /** The highest published stable version up to the declared one, yanked ones included. */
+    readonly baseline?: string;
+    /** The level the changes since the baseline require. */
+    readonly level?: BumpLevel;
+    /** The level after the 0.x rule. */
+    readonly effective?: BumpLevel;
+    /** The smallest version the changes admit, a pre-release such as `2.0.0-0`. */
+    readonly minimum?: string;
+    /** The stable form of the required version, such as `2.0.0`. */
+    readonly next?: string;
+    /** For a refused pre-release, the first pre-release of the required version on its channel. */
+    readonly suggestion?: string;
+    /**
+     * The declared version reaches the minimum, or there is nothing to compare. It judges an
+     * unpublished version: a published stable one is its own baseline and is never accepted, so a
+     * consumer decides on `published || accepted`, the exit status.
+     */
+    readonly accepted: boolean;
+    /** Every change since the baseline, ordered by subject Key then observation; empty for none. */
+    readonly changes: readonly DiffChangeV1[];
+}
+export interface DiffInput {
+    readonly origin: string;
+    readonly declared: Version;
+    /**
+     * Which published versions can be the baseline (AM-23): `diff` compares with the highest stable
+     * version up to the declared one (`<=`, the default); `publish`, which never runs for a published
+     * version, with the highest one below it (`<`).
+     */
+    readonly bound?: '<' | '<=';
+    /** The Schema revision the Project builds now. */
+    readonly revision: string;
+    /** The caller's view of the registry; `undefined` when it holds no readable Domain of `origin`. */
+    readonly index: RegistryIndex | undefined;
+    /** The Schema the Project builds now. */
+    readonly current: () => DomainSchema;
+    /** The build digest of every distinct bundler; read only when the Schema revision is unchanged. */
+    readonly builds: () => Promise<readonly string[]>;
+    /** The Schema a Publication names; read only when its revision differs from the Project's. */
+    readonly published: (publication: RegistryPublication) => Promise<DomainSchema>;
+}
+/**
+ * Compare the Project with the highest published stable version up to the declared one
+ * (`baselineVersion(index, declared, '<=')`, or below it for `publish`, AM-23) and judge the declared version against the
+ * level its changes require (tech Versioning [.21507], [.106102]). The judgement always receives a
+ * level beside its baseline (AM-56): the compatibility engine's when the Schema revision changed,
+ * otherwise patch, the smallest level, which `diff` picks itself when nothing changed at all.
+ */
+export declare function diffReport(input: DiffInput): Promise<DiffReportV1>;
+/**
+ * Decode the bundle a Publication stores and admit it only as that Publication's Schema: the
+ * Domain's origin and the Publication's Schema revision.
+ */
+export declare function publishedSchema(bytes: Uint8Array, publication: RegistryPublication, origin: string): DomainSchema;

package/dist/tooling/cli/diff/report.js

@@ -0,0 +1,154 @@
+import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
+import { requiredBump } from '@astrale-os/kernel-dsl/v1/schema/compatibility';
+import { revision } from '@astrale-os/kernel-dsl/v1/schema/revision';
+import { baselineVersion, judgeVersion } from '../../../platform/versioning/index.js';
+/**
+ * Compare the Project with the highest published stable version up to the declared one
+ * (`baselineVersion(index, declared, '<=')`, or below it for `publish`, AM-23) and judge the declared version against the
+ * level its changes require (tech Versioning [.21507], [.106102]). The judgement always receives a
+ * level beside its baseline (AM-56): the compatibility engine's when the Schema revision changed,
+ * otherwise patch, the smallest level, which `diff` picks itself when nothing changed at all.
+ */
+export async function diffReport(input) {
+    const identity = {
+        format: 'astrale.diff-report',
+        version: 1,
+        origin: input.origin,
+        declared: input.declared,
+    };
+    if (input.index === undefined) {
+        return Object.freeze({
+            ...identity,
+            published: false,
+            registry: 'unregistered',
+            accepted: true,
+            changes: Object.freeze([]),
+        });
+    }
+    const publications = input.index.publications;
+    const published = publications.some(({ version }) => version === input.declared);
+    // An index entry that is not a canonical version is never a baseline: `baselineVersion` keeps
+    // only canonical stable versions (AM-56), so the registry's strings need no admission here.
+    const index = publications.map(({ version, yanked }) => ({
+        version: version,
+        yanked,
+    }));
+    const baseline = baselineVersion(index, input.declared, input.bound ?? '<=');
+    if (baseline === undefined) {
+        // Without a stable version before it there is nothing to check (tech [.106102]).
+        const verdict = judgeVersion({ declared: input.declared });
+        return Object.freeze({
+            ...identity,
+            published,
+            registry: 'read',
+            accepted: verdict.accepted,
+            changes: Object.freeze([]),
+        });
+    }
+    const publication = publications.find(({ version }) => version === baseline);
+    const { level, changes } = await changesSince(publication, input);
+    const verdict = judgeVersion({ declared: input.declared, previous: baseline, level });
+    return Object.freeze({
+        ...identity,
+        published,
+        registry: 'read',
+        baseline,
+        level,
+        effective: verdict.effective,
+        minimum: verdict.minimum,
+        next: verdict.next,
+        ...(verdict.suggestion === undefined ? {} : { suggestion: verdict.suggestion }),
+        accepted: verdict.accepted,
+        changes,
+    });
+}
+/**
+ * Decode the bundle a Publication stores and admit it only as that Publication's Schema: the
+ * Domain's origin and the Publication's Schema revision.
+ */
+export function publishedSchema(bytes, publication, origin) {
+    const root = bundle.decode(bytes).root;
+    if (root.origin !== origin || revision(root) !== publication.schemaRevision) {
+        throw new TypeError(`The stored bundle of ${origin}@${publication.version} is not that Publication's Schema ${publication.schemaRevision}.`);
+    }
+    return root;
+}
+async function changesSince(publication, input) {
+    if (publication.schemaRevision !== input.revision) {
+        const required = requiredBump(await input.published(publication), input.current());
+        const changes = required.changes.map(change);
+        return {
+            level: required.level,
+            changes: Object.freeze(changes.length > 0
+                ? changes
+                : // A new revision whose meaning the engine finds equivalent, such as descriptions.
+                    [
+                        Object.freeze({
+                            subject: input.origin,
+                            facet: 'schema',
+                            state: 'changed',
+                            bump: 'patch',
+                            detail: 'same meaning',
+                        }),
+                    ]),
+        };
+    }
+    const builds = await input.builds();
+    if (builds.includes(publication.buildDigest)) {
+        // No change at all: same build digest and no row of [.21507] (AM-56).
+        return { level: 'patch', changes: Object.freeze([]) };
+    }
+    // Code only, same Schema revision ([.21507], first row).
+    return {
+        level: 'patch',
+        changes: Object.freeze([
+            Object.freeze({
+                subject: input.origin,
+                facet: 'build',
+                state: 'changed',
+                bump: 'patch',
+                detail: `${publication.buildDigest} → ${builds.length === 0 ? 'none' : builds.join(', ')}`,
+            }),
+        ]),
+    };
+}
+function change({ subject, observation, bump }) {
+    const detail = describe(observation);
+    return Object.freeze({
+        subject: subject.key,
+        facet: observation.facet,
+        // `requiredBump` lists only observations that are not equal.
+        state: observation.state,
+        bump,
+        ...(detail === undefined ? {} : { detail }),
+    });
+}
+const DETAILED_DIFFERENCES = 3;
+const VALUE_LENGTH = 40;
+/** The observation's differences in a few words: `optional → required`, `input/type: "string" → "number"`. */
+function describe(observation) {
+    const differences = observation.differences;
+    if (differences.length === 0)
+        return undefined;
+    const [first] = differences;
+    if (differences.length === 1 &&
+        first.path === '/required' &&
+        typeof first.before === 'boolean' &&
+        typeof first.after === 'boolean') {
+        return first.after ? 'optional → required' : 'required → optional';
+    }
+    const described = differences.slice(0, DETAILED_DIFFERENCES).map((difference) => {
+        const path = difference.path === '' ? '/' : difference.path.slice(1);
+        if (difference.before === undefined)
+            return `${path}: added ${value(difference.after)}`;
+        if (difference.after === undefined)
+            return `${path}: removed ${value(difference.before)}`;
+        return `${path}: ${value(difference.before)} → ${value(difference.after)}`;
+    });
+    const more = differences.length - described.length;
+    return more > 0 ? `${described.join('; ')}; ${more} more` : described.join('; ');
+}
+function value(input) {
+    const text = JSON.stringify(input) ?? String(input);
+    return text.length > VALUE_LENGTH ? `${text.slice(0, VALUE_LENGTH - 1)}…` : text;
+}

package/dist/tooling/cli/dotenv.d.ts

@@ -7,6 +7,8 @@
  * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
  * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
  */
+/** Parse one dotenv document into a flat record; `${VAR}` reads only earlier keys. */
+export declare function parseDotenv(contents: string): Record<string, string>;
 /**
  * Read + parse a dotenv file the preset explicitly DECLARED (`secrets:`).
  * Declared-but-absent is a wiring error (the gitignored file was never created
@@ -15,5 +17,3 @@
  * that exists but holds no keys is legitimate (a domain with no secrets yet).
  */
 export declare function loadDeclaredSecrets(path: string, declaration: string): Record<string, string>;
-/** Load one explicit development-session secret snapshot without following a leaf symlink. */
-export declare function loadPrivateSecretsFile(path: string, platform?: NodeJS.Platform): Record<string, string>;

package/dist/tooling/cli/dotenv.js

@@ -7,8 +7,9 @@
  * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
  * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
  */
-import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs';
-function parseDotenv(contents) {
+import { readFileSync } from 'node:fs';
+/** Parse one dotenv document into a flat record; `${VAR}` reads only earlier keys. */
+export function parseDotenv(contents) {
     const out = {};
     for (const raw of contents.split('\n')) {
         const line = raw.trim();
@@ -52,34 +53,3 @@ export function loadDeclaredSecrets(path, declaration) {
     }
     return parseDotenv(contents);
 }
-/** Load one explicit development-session secret snapshot without following a leaf symlink. */
-export function loadPrivateSecretsFile(path, platform = process.platform) {
-    if (platform === 'win32') {
-        throw new Error('--secrets-file is unavailable on Windows until private no-reparse file admission is supported.');
-    }
-    let descriptor;
-    try {
-        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-    }
-    catch (cause) {
-        if (cause instanceof Error && 'code' in cause && cause.code === 'ENOENT') {
-            throw new Error(`Secrets file '${path}' is missing.`, { cause });
-        }
-        if (cause instanceof Error && 'code' in cause && cause.code === 'ELOOP') {
-            throw new Error(`Secrets file '${path}' must be a regular file and not a symlink.`, { cause });
-        }
-        throw cause;
-    }
-    try {
-        const info = fstatSync(descriptor);
-        if (!info.isFile())
-            throw new Error(`Secrets file '${path}' must be a regular file.`);
-        if ((info.mode & 0o077) !== 0) {
-            throw new Error(`Secrets file '${path}' must not be accessible by group or other users.`);
-        }
-        return parseDotenv(readFileSync(descriptor, 'utf8'));
-    }
-    finally {
-        closeSync(descriptor);
-    }
-}