@owlmeans/viable-common 0.0.4

package/build/slot/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/slot/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AAEzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEtE,eAAO,MAAM,wBAAwB,EAsBhC,cAAc,CAAC,kBAAkB,CAAC,CAAA;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAUnB,cAAc,CAAC,gBAAgB,CAAC,CAAA"}

package/build/slot/schemas.js

@@ -0,0 +1,43 @@
+import { SlotCommandType, SlotFileCommand, SlotGitCommand, SlotShellCommand } from './consts.js';
+export const SlotCommandPayloadSchema = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            enum: Object.values(SlotCommandType)
+        },
+        command: {
+            oneOf: [
+                { type: 'string', enum: Object.values(SlotFileCommand) },
+                { type: 'string', enum: Object.values(SlotShellCommand) },
+                { type: 'string', enum: Object.values(SlotGitCommand) },
+            ]
+        },
+        args: {
+            type: 'object',
+            nullable: true,
+            additionalProperties: true
+        }
+    },
+    required: ['type', 'command'],
+    additionalProperties: false
+};
+/**
+ * The clone command's arguments, as a signed body carries them.
+ *
+ * `token` is declared because it is SENT — a body field the schema does not declare is stripped
+ * by validation and then verified against a signature the sender made over the whole thing, which
+ * the guard reports as a 401 rather than as the validation gap it is.
+ */
+export const SlotGitCloneArgsSchema = {
+    type: 'object',
+    properties: {
+        remoteUrl: { type: 'string', minLength: 1, maxLength: 2048 },
+        branch: { type: 'string', maxLength: 256, nullable: true },
+        depth: { type: 'number', minimum: 0, nullable: true },
+        token: { type: 'string', maxLength: 4096, nullable: true },
+    },
+    required: ['remoteUrl'],
+    additionalProperties: false,
+};
+//# sourceMappingURL=schemas.js.map

package/build/slot/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/slot/schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGhG,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;SACrC;QACD,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE;gBACxD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE;gBACzD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE;aACxD;SACF;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,IAAI;SAC3B;KACF;IACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;IAC7B,oBAAoB,EAAE,KAAK;CACU,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;QAC5D,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC1D,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;QACrD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC3D;IACD,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,oBAAoB,EAAE,KAAK;CACmB,CAAA"}

package/build/slot/types.d.ts

@@ -0,0 +1,147 @@
+import type { SlotCommandType, SlotFileCommand, SlotGitCommand, SlotShellCommand, SubProject } from './consts.js';
+export type SlotCommand = SlotFileCommand | SlotShellCommand | SlotGitCommand;
+export interface SlotCommandPayload {
+    type: SlotCommandType;
+    command: SlotCommand;
+    args?: Record<string, any>;
+}
+/**
+ * What a shell command answers with.
+ *
+ * `result` is the contract every caller reads: **error text, or `null` for success**. It is not a
+ * transcript — a command that fails returns the diagnostics a fixer or a person can act on, and a
+ * command that succeeds returns nothing at all. The remaining fields belong to the two commands
+ * that report a JOB rather than a verdict ({@link SlotShellCommand.BootCheck} and its status read)
+ * and to the integrity check, which reports a refusal rather than a failure.
+ */
+export interface SlotShellResult {
+    result: string | null;
+    /** BootCheck: the job was started; the verdict comes from a BootCheckStatus read. */
+    started?: boolean;
+    /** BootCheckStatus: whether a check is still in flight, and when it began. */
+    running?: boolean;
+    startedAt?: string;
+    /** BootCheckStatus: a verdict is available in `result`. */
+    done?: boolean;
+    /** The target's own boot phase, when it got far enough to report one. */
+    phase?: string;
+    /** Integrity: whether the tree still holds the generated application. */
+    ok?: boolean;
+    violations?: string[];
+}
+/**
+ * The shapes the git commands answer with.
+ *
+ * Redeclared here rather than imported: the implementation lives in a package that carries
+ * `simple-git` and a GitHub client, and the connector — which executes these commands through the
+ * `git` CLI on a developer's machine — must not depend on either. The platform keeps answering
+ * with its own richer types; these are the subset both ends agree on.
+ */
+export interface SlotGitFileChange {
+    path: string;
+    status: string;
+}
+export interface SlotGitCommitInfo {
+    hash: string;
+    shortHash: string;
+    subject: string;
+    authorName: string;
+    authorEmail: string;
+    committedAt: string;
+}
+export interface SlotGitStatus {
+    initialized: boolean;
+    head: SlotGitCommitInfo | null;
+    branch: string;
+    dirty: boolean;
+    changedFiles: number;
+    files: SlotGitFileChange[];
+    remoteUrl: string | null;
+    ahead: number | null;
+    behind: number | null;
+}
+export interface SlotGitCommitResult {
+    commit: SlotGitCommitInfo | null;
+}
+export interface SlotGitLogResult {
+    commits: SlotGitCommitInfo[];
+}
+/**
+ * Bring a remote repository onto the volume.
+ *
+ * `token` is a per-invocation credential and never reaches the tree: the executor passes it
+ * through the process environment for the one fetch, exactly as push and pull already do, so it
+ * appears in no `.git/config`, no remote URL and no argv anything can observe.
+ */
+export interface SlotGitCloneArgs {
+    remoteUrl: string;
+    /** The branch to check out. Absent means whatever the remote calls its default. */
+    branch?: string;
+    /** Fetch depth; 0 means the whole history. Defaults to a shallow fetch. */
+    depth?: number;
+    token?: string;
+}
+export interface SlotGitCloneResult {
+    cloned: boolean;
+    /** The branch actually checked out — the resolved default, when none was asked for. */
+    branch: string;
+    head: SlotGitCommitInfo | null;
+    /** Executor diagnostics, when it has any worth reporting. */
+    result?: string;
+}
+/**
+ * One entry of a {@link SlotFileCommand.StatTree} listing.
+ *
+ * The shape both a publisher and a connector answer with, so a census walks a pod's volume and a
+ * developer's own directory through one contract. `binary` is the executor's own verdict — the
+ * caller has not read the file and cannot form one.
+ */
+export interface FileStat {
+    path: string;
+    bytes: number;
+    binary: boolean;
+    modifiedAt?: string;
+}
+export interface StatTreeArgs {
+    /** Project-relative directory to walk. Absent means the whole project. */
+    dir?: string;
+    /** Entries to return before the answer reports itself truncated. */
+    limit?: number;
+}
+/**
+ * `total` is what the walk SAW, `entries` what it returned.
+ *
+ * The two differ on a truncated walk, and the difference is what tells a caller its picture of the
+ * tree is partial — a bounded listing that reported only what it returned would be indistinguish-
+ * able from a small repository.
+ */
+export interface StatTreeResult {
+    entries: FileStat[];
+    truncated: boolean;
+    total: number;
+}
+export interface ReadHeadArgs {
+    path: string;
+    bytes: number;
+}
+/** Move everything in the project root under `dir`, leaving the named entries where they are. */
+export interface RelocateArgs {
+    dir: string;
+    /** Root-relative names that stay put — the slot's own metadata and markers. */
+    keep?: string[];
+}
+export interface RelocateResult {
+    moved: number;
+    kept: string[];
+}
+export interface RemoveTreeArgs {
+    dir: string;
+}
+/** Arguments a shell command may carry. */
+export interface SlotShellArgs {
+    subproject?: SubProject;
+    /** Free-form arguments for {@link SlotShellCommand.Bun}; absent means a plain install. */
+    args?: string;
+    skipBuild?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/slot/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/slot/types.ts"],"names":[],"mappings":"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"}

package/build/slot/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/slot/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/slot/types.ts"],"names":[],"mappings":""}

package/build/topology/card.d.ts

@@ -0,0 +1,23 @@
+import type { TopologyDescriptor } from './types.js';
+/** What `.agents/memory/topology.md` carries in its frontmatter. */
+export interface TopologyMeta extends TopologyDescriptor {
+    version: number;
+    updatedAt: string;
+}
+/**
+ * Narrow a parsed frontmatter block into a topology, or answer `null`.
+ *
+ * `null` means "use the layout default", and every caller treats it that way. A topology file
+ * written by a platform version this one cannot read must not stop a project from building — the
+ * arrangement it describes is almost certainly still the default one.
+ */
+export declare const parseTopologyMeta: (data: unknown) => TopologyDescriptor | null;
+export declare const topologyMeta: (topology: TopologyDescriptor) => TopologyMeta;
+/**
+ * The body of `.agents/memory/topology.md` — what a model reads, and what a person reads.
+ *
+ * Rendered from the descriptor rather than maintained beside it, for the same reason the layout
+ * tables are: a card that disagrees with the frontmatter teaches the wrong tree.
+ */
+export declare const renderTopologyCard: (topology: TopologyDescriptor) => string;
+//# sourceMappingURL=card.d.ts.map

package/build/topology/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../src/topology/card.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAA8C,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEhG,oEAAoE;AACpE,MAAM,WAAW,YAAa,SAAQ,kBAAkB;IACtD,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAqCD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,SAAU,OAAO,KAAG,kBAAkB,GAAG,IActE,CAAA;AAED,eAAO,MAAM,YAAY,aAAc,kBAAkB,KAAG,YAK1D,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,aAAc,kBAAkB,KAAG,MAuBjE,CAAA"}

package/build/topology/card.js

@@ -0,0 +1,95 @@
+import { SubProject } from '../slot/consts.js';
+import { TOPOLOGY_VERSION } from './consts.js';
+import { orderPackages } from './helpers.js';
+const ROLES = new Set(Object.values(SubProject));
+const KINDS = new Set(['library', 'bundle']);
+const asStrings = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+/**
+ * Read a package descriptor out of whatever the file held.
+ *
+ * Everything is narrowed rather than trusted: the file is on the target's volume, where a person,
+ * a GitHub pull or a previous platform version may have written it. A descriptor that cannot be
+ * narrowed is DROPPED, never repaired — a package with no name or no recognisable role would
+ * otherwise resolve a path somewhere real and wrong.
+ */
+const parsePackage = (value) => {
+    if (value == null || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const name = typeof raw.name === 'string' ? raw.name.trim() : '';
+    if (name === '' || name.includes('/') || name.startsWith('.'))
+        return null;
+    const roles = asStrings(raw.roles).filter((role) => ROLES.has(role));
+    if (roles.length === 0)
+        return null;
+    const kind = KINDS.has(raw.kind) ? raw.kind : 'bundle';
+    const areas = asStrings(raw.areas);
+    const queues = asStrings(raw.queues);
+    return {
+        name,
+        roles,
+        kind,
+        dependsOn: asStrings(raw.dependsOn),
+        ...(areas.length > 0 ? { areas: areas } : {}),
+        ...(queues.length > 0 ? { queues } : {}),
+    };
+};
+/**
+ * Narrow a parsed frontmatter block into a topology, or answer `null`.
+ *
+ * `null` means "use the layout default", and every caller treats it that way. A topology file
+ * written by a platform version this one cannot read must not stop a project from building — the
+ * arrangement it describes is almost certainly still the default one.
+ */
+export const parseTopologyMeta = (data) => {
+    if (data == null || typeof data !== 'object')
+        return null;
+    const raw = data;
+    if (typeof raw.dir !== 'string' || raw.dir.trim() === '')
+        return null;
+    const packages = Array.isArray(raw.packages)
+        ? raw.packages.map(parsePackage).filter((pkg) => pkg != null)
+        : [];
+    if (packages.length === 0)
+        return null;
+    return {
+        id: typeof raw.id === 'string' && raw.id !== '' ? raw.id : 'recorded',
+        dir: raw.dir.trim(),
+        packages,
+    };
+};
+export const topologyMeta = (topology) => ({
+    ...topology,
+    packages: orderPackages(topology.packages),
+    version: TOPOLOGY_VERSION,
+    updatedAt: new Date().toISOString(),
+});
+/**
+ * The body of `.agents/memory/topology.md` — what a model reads, and what a person reads.
+ *
+ * Rendered from the descriptor rather than maintained beside it, for the same reason the layout
+ * tables are: a card that disagrees with the frontmatter teaches the wrong tree.
+ */
+export const renderTopologyCard = (topology) => {
+    const ordered = orderPackages(topology.packages);
+    const rows = ordered.map(pkg => {
+        const deps = pkg.dependsOn.length > 0 ? pkg.dependsOn.join(', ') : '—';
+        const extra = [
+            ...(pkg.areas != null ? [`areas: ${pkg.areas.join(', ')}`] : []),
+            ...(pkg.queues != null ? [`queues: ${pkg.queues.join(', ')}`] : []),
+        ].join('; ');
+        return `| \`${topology.dir}/${pkg.name}\` | ${pkg.roles.join(', ')} | ${pkg.kind} | ${deps} | ${extra === '' ? '—' : extra} |`;
+    });
+    return [
+        '# Topology',
+        '',
+        'Which packages this project has, what each one is, and which compile against which.',
+        'Built in the order of the table — a `library` must be built before anything importing it.',
+        '',
+        '| Package | Roles | Kind | Depends on | Notes |',
+        '|---|---|---|---|---|',
+        ...rows,
+        '',
+    ].join('\n');
+};
+//# sourceMappingURL=card.js.map

package/build/topology/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../src/topology/card.ts"],"names":[],"mappings":"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"}

package/build/topology/consts.d.ts

@@ -0,0 +1,32 @@
+import { TargetLayout } from '../integrity/consts.js';
+import type { TopologyDescriptor } from './types.js';
+/**
+ * The two arrangements the platform itself writes.
+ *
+ * They are the DEFAULTS a project falls back to, not the set of arrangements that can exist: a
+ * project records its own topology and may hold packages neither of these names. What makes them
+ * special is only that `detectTargetLayout` can recognise them from the disk, which is what a
+ * consumer needs when a project predates the topology file entirely.
+ *
+ * v1 is frozen. A target's tree is the one it was initialized with, so nothing is ever added here.
+ */
+export declare const DEFAULT_TOPOLOGY: TopologyDescriptor;
+/**
+ * The pre-restructure arrangement, frozen.
+ *
+ * `backend` here is the HTTP SERVER and `frontend` the browser app — the same two words the
+ * current topology uses for other things, which is why roles are mapped per topology and never
+ * joined onto a path.
+ */
+export declare const LEGACY_TOPOLOGY: TopologyDescriptor;
+/** The default topology for each layout the platform can detect on disk. */
+export declare const LAYOUT_TOPOLOGIES: Readonly<Record<TargetLayout, TopologyDescriptor>>;
+/**
+ * The frontmatter version of `.agents/memory/topology.md`.
+ *
+ * A file written by an older platform is READ, never refused: an unknown or missing version falls
+ * back to the layout default, because a topology nobody can parse must not stop a project from
+ * building.
+ */
+export declare const TOPOLOGY_VERSION = 1;
+//# sourceMappingURL=consts.d.ts.map

package/build/topology/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../src/topology/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,kBAY9B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,kBAQ7B,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAGhF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAA"}

package/build/topology/consts.js

@@ -0,0 +1,55 @@
+import { TargetLayout } from '../integrity/consts.js';
+import { SubProject } from '../slot/consts.js';
+/**
+ * The two arrangements the platform itself writes.
+ *
+ * They are the DEFAULTS a project falls back to, not the set of arrangements that can exist: a
+ * project records its own topology and may hold packages neither of these names. What makes them
+ * special is only that `detectTargetLayout` can recognise them from the disk, which is what a
+ * consumer needs when a project predates the topology file entirely.
+ *
+ * v1 is frozen. A target's tree is the one it was initialized with, so nothing is ever added here.
+ */
+export const DEFAULT_TOPOLOGY = {
+    id: 'owlmeans-fullstack',
+    dir: 'sources',
+    packages: [
+        { name: 'common', roles: [SubProject.Common], kind: 'library', dependsOn: [] },
+        // The shared LIBRARY, not the server — that is `api`. It owns the context factory, the config,
+        // the resources, the services, the domain models and the job processors.
+        { name: 'backend', roles: [SubProject.Backend], kind: 'library', dependsOn: ['common'] },
+        { name: 'api', roles: [SubProject.Api], kind: 'bundle', dependsOn: ['common', 'backend'] },
+        { name: 'web', roles: [SubProject.Web, SubProject.Frontend], kind: 'bundle', dependsOn: ['common'] },
+        { name: 'worker', roles: [SubProject.Worker], kind: 'bundle', dependsOn: ['common', 'backend'] },
+    ],
+};
+/**
+ * The pre-restructure arrangement, frozen.
+ *
+ * `backend` here is the HTTP SERVER and `frontend` the browser app — the same two words the
+ * current topology uses for other things, which is why roles are mapped per topology and never
+ * joined onto a path.
+ */
+export const LEGACY_TOPOLOGY = {
+    id: 'owlmeans-fullstack-v1',
+    dir: 'packages',
+    packages: [
+        { name: 'common', roles: [SubProject.Common], kind: 'library', dependsOn: [] },
+        { name: 'backend', roles: [SubProject.Backend, SubProject.Api], kind: 'bundle', dependsOn: ['common'] },
+        { name: 'frontend', roles: [SubProject.Frontend, SubProject.Web], kind: 'bundle', dependsOn: ['common'] },
+    ],
+};
+/** The default topology for each layout the platform can detect on disk. */
+export const LAYOUT_TOPOLOGIES = {
+    [TargetLayout.V2]: DEFAULT_TOPOLOGY,
+    [TargetLayout.V1]: LEGACY_TOPOLOGY,
+};
+/**
+ * The frontmatter version of `.agents/memory/topology.md`.
+ *
+ * A file written by an older platform is READ, never refused: an unknown or missing version falls
+ * back to the layout default, because a topology nobody can parse must not stop a project from
+ * building.
+ */
+export const TOPOLOGY_VERSION = 1;
+//# sourceMappingURL=consts.js.map

package/build/topology/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../../src/topology/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAG9C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB;IAClD,EAAE,EAAE,oBAAoB;IACxB,GAAG,EAAE,SAAS;IACd,QAAQ,EAAE;QACR,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE;QAC9E,+FAA+F;QAC/F,yEAAyE;QACzE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE;QACxF,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE;QAC1F,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE;QACpG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE;KACjG;CACF,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAuB;IACjD,EAAE,EAAE,uBAAuB;IAC3B,GAAG,EAAE,UAAU;IACf,QAAQ,EAAE;QACR,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE;QAC9E,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE;QACvG,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE;KAC1G;CACF,CAAA;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,iBAAiB,GAAuD;IACnF,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,gBAAgB;IACnC,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,eAAe;CACnC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAA"}

package/build/topology/helpers.d.ts

@@ -0,0 +1,44 @@
+import { TargetLayout } from '../integrity/consts.js';
+import type { ProjectArea } from '../areas/consts.js';
+import type { SubProject } from '../slot/consts.js';
+import type { ResolvedTopology, TargetPackageDescriptor, TopologyDescriptor } from './types.js';
+/**
+ * Order the packages so that nothing is built before what it compiles against.
+ *
+ * Kahn's algorithm, with two deliberate tolerances. An edge to a package the topology does not
+ * hold is DROPPED rather than fatal — a project may declare a dependency on something a pull has
+ * not brought in yet, and refusing to order the tree would take the whole build down over one
+ * name. A cycle leaves its members unvisited, and they are appended in declaration order: a cycle
+ * cannot be built correctly in any order, so the useful behaviour is to build it in the order
+ * somebody wrote rather than to throw.
+ */
+export declare const orderPackages: (packages: TargetPackageDescriptor[]) => TargetPackageDescriptor[];
+/** Resolve the derived halves — build order, library order and the role index. */
+export declare const resolveTopology: (topology: TopologyDescriptor) => ResolvedTopology;
+/** The default topology for a layout already decided. */
+export declare const topologyOf: (layout: TargetLayout) => TopologyDescriptor;
+/**
+ * The directory a role names, or `null` when this topology has no package for it.
+ *
+ * `null` rather than the role's own name: a command aimed at a package the tree does not have must
+ * fail where it is issued. Answering with a plausible directory runs it somewhere real and wrong,
+ * which is how a type check once ran against the shared package instead of the one under repair.
+ */
+export declare const packageForRole: (topology: ResolvedTopology, role: SubProject) => TargetPackageDescriptor | null;
+/** Every package holding a role — more than one only where a topology splits that role. */
+export declare const packagesForRole: (topology: ResolvedTopology, role: SubProject) => TargetPackageDescriptor[];
+/** The package serving an area, for a topology that splits the browser app across several. */
+export declare const packageForArea: (topology: ResolvedTopology, role: SubProject, area: ProjectArea) => TargetPackageDescriptor | null;
+/** `<dir>/<package>` — the only place a topology directory is composed. */
+export declare const packageDir: (topology: TopologyDescriptor, pkg: TargetPackageDescriptor) => string;
+/**
+ * Merge a package into a topology, by name.
+ *
+ * This is the ADOPTION path: a package that arrived with a GitHub pull is classified once and
+ * recorded here, so the next run addresses the tree that exists rather than re-deriving one that
+ * does not. Replacing by name rather than appending keeps a re-classification idempotent.
+ */
+export declare const withPackage: (topology: TopologyDescriptor, pkg: TargetPackageDescriptor) => TopologyDescriptor;
+/** Whether two topologies describe the same arrangement — used to skip a needless rewrite. */
+export declare const sameTopology: (a: TopologyDescriptor, b: TopologyDescriptor) => boolean;
+//# sourceMappingURL=helpers.d.ts.map

package/build/topology/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/topology/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,KAAK,EACV,gBAAgB,EAAE,uBAAuB,EAAE,kBAAkB,EAC9D,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,aAAc,uBAAuB,EAAE,KAAG,uBAAuB,EA4C1F,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,eAAe,aAAc,kBAAkB,KAAG,gBAgB9D,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,UAAU,WAAY,YAAY,KAAG,kBACH,CAAA;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,aACf,gBAAgB,QAAQ,UAAU,KAC3C,uBAAuB,GAAG,IAA0C,CAAA;AAEvE,2FAA2F;AAC3F,eAAO,MAAM,eAAe,aAChB,gBAAgB,QAAQ,UAAU,KAC3C,uBAAuB,EAAiC,CAAA;AAE3D,8FAA8F;AAC9F,eAAO,MAAM,cAAc,aACf,gBAAgB,QAAQ,UAAU,QAAQ,WAAW,KAC9D,uBAAuB,GAAG,IAM5B,CAAA;AAED,2EAA2E;AAC3E,eAAO,MAAM,UAAU,aAAc,kBAAkB,OAAO,uBAAuB,KAAG,MACzD,CAAA;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,aACZ,kBAAkB,OAAO,uBAAuB,KACzD,kBAKD,CAAA;AAEF,8FAA8F;AAC9F,eAAO,MAAM,YAAY,MAAO,kBAAkB,KAAK,kBAAkB,KAAG,OAEtD,CAAA"}

package/build/topology/helpers.js

@@ -0,0 +1,112 @@
+import { LAYOUT_TOPOLOGIES, DEFAULT_TOPOLOGY } from './consts.js';
+/**
+ * Order the packages so that nothing is built before what it compiles against.
+ *
+ * Kahn's algorithm, with two deliberate tolerances. An edge to a package the topology does not
+ * hold is DROPPED rather than fatal — a project may declare a dependency on something a pull has
+ * not brought in yet, and refusing to order the tree would take the whole build down over one
+ * name. A cycle leaves its members unvisited, and they are appended in declaration order: a cycle
+ * cannot be built correctly in any order, so the useful behaviour is to build it in the order
+ * somebody wrote rather than to throw.
+ */
+export const orderPackages = (packages) => {
+    const known = new Set(packages.map(pkg => pkg.name));
+    const index = new Map(packages.map((pkg, at) => [pkg.name, at]));
+    const pending = new Map(packages.map(pkg => [
+        pkg.name, pkg.dependsOn.filter(dep => known.has(dep) && dep !== pkg.name).length,
+    ]));
+    const dependents = new Map();
+    for (const pkg of packages) {
+        for (const dep of pkg.dependsOn) {
+            if (!known.has(dep) || dep === pkg.name)
+                continue;
+            dependents.set(dep, [...dependents.get(dep) ?? [], pkg.name]);
+        }
+    }
+    const byName = new Map(packages.map(pkg => [pkg.name, pkg]));
+    const out = [];
+    // Ready packages are taken in DECLARATION order, not in the order they became ready. Both are
+    // correct builds; only one is the same list every time and the same list a person wrote, and
+    // this order is compared against the shipped layout tables by a test.
+    const ready = packages.filter(pkg => pending.get(pkg.name) === 0).map(pkg => pkg.name);
+    const take = () => {
+        if (ready.length === 0)
+            return undefined;
+        let at = 0;
+        for (let i = 1; i < ready.length; i++) {
+            if ((index.get(ready[i]) ?? 0) < (index.get(ready[at]) ?? 0))
+                at = i;
+        }
+        return ready.splice(at, 1)[0];
+    };
+    for (let name = take(); name != null; name = take()) {
+        const pkg = byName.get(name);
+        if (pkg == null)
+            continue;
+        out.push(pkg);
+        for (const next of dependents.get(name) ?? []) {
+            const left = (pending.get(next) ?? 0) - 1;
+            pending.set(next, left);
+            if (left === 0)
+                ready.push(next);
+        }
+    }
+    const seen = new Set(out.map(pkg => pkg.name));
+    return [...out, ...packages.filter(pkg => !seen.has(pkg.name))];
+};
+/** Resolve the derived halves — build order, library order and the role index. */
+export const resolveTopology = (topology) => {
+    const ordered = orderPackages(topology.packages);
+    const byRole = {};
+    for (const pkg of ordered) {
+        for (const role of pkg.roles) {
+            byRole[role] = [...byRole[role] ?? [], pkg];
+        }
+    }
+    return {
+        ...topology,
+        packages: ordered,
+        build: ordered.map(pkg => pkg.name),
+        libraries: ordered.filter(pkg => pkg.kind === 'library').map(pkg => pkg.name),
+        byRole,
+    };
+};
+/** The default topology for a layout already decided. */
+export const topologyOf = (layout) => LAYOUT_TOPOLOGIES[layout] ?? DEFAULT_TOPOLOGY;
+/**
+ * The directory a role names, or `null` when this topology has no package for it.
+ *
+ * `null` rather than the role's own name: a command aimed at a package the tree does not have must
+ * fail where it is issued. Answering with a plausible directory runs it somewhere real and wrong,
+ * which is how a type check once ran against the shared package instead of the one under repair.
+ */
+export const packageForRole = (topology, role) => topology.byRole[role]?.[0] ?? null;
+/** Every package holding a role — more than one only where a topology splits that role. */
+export const packagesForRole = (topology, role) => topology.byRole[role] ?? [];
+/** The package serving an area, for a topology that splits the browser app across several. */
+export const packageForArea = (topology, role, area) => {
+    const candidates = packagesForRole(topology, role);
+    return candidates.find(pkg => pkg.areas?.includes(area) === true)
+        ?? candidates.find(pkg => pkg.areas == null)
+        ?? candidates[0]
+        ?? null;
+};
+/** `<dir>/<package>` — the only place a topology directory is composed. */
+export const packageDir = (topology, pkg) => `${topology.dir}/${pkg.name}`;
+/**
+ * Merge a package into a topology, by name.
+ *
+ * This is the ADOPTION path: a package that arrived with a GitHub pull is classified once and
+ * recorded here, so the next run addresses the tree that exists rather than re-deriving one that
+ * does not. Replacing by name rather than appending keeps a re-classification idempotent.
+ */
+export const withPackage = (topology, pkg) => ({
+    ...topology,
+    packages: topology.packages.some(known => known.name === pkg.name)
+        ? topology.packages.map(known => known.name === pkg.name ? pkg : known)
+        : [...topology.packages, pkg],
+});
+/** Whether two topologies describe the same arrangement — used to skip a needless rewrite. */
+export const sameTopology = (a, b) => JSON.stringify(orderPackages(a.packages)) === JSON.stringify(orderPackages(b.packages))
+    && a.dir === b.dir;
+//# sourceMappingURL=helpers.js.map

package/build/topology/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/topology/helpers.ts"],"names":[],"mappings":"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"}

package/build/topology/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './helpers.js';
+export * from './card.js';
+//# sourceMappingURL=index.d.ts.map

package/build/topology/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA"}

package/build/topology/index.js

@@ -0,0 +1,4 @@
+export * from './consts.js';
+export * from './helpers.js';
+export * from './card.js';
+//# sourceMappingURL=index.js.map

package/build/topology/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA"}