@jam-overture/loom/cli

DEFAULT_DIRECTORYvalue

const DEFAULT_DIRECTORY = "loom"

parseArgumentsfunction

const parseArguments: (argv: readonly string[]) => Result<CliCommand, CliError>

FileSysteminterface

interface FileSystem {
    readonly list: (directory: string) => Promise<Result<readonly string[], string>>;
    readonly write: (path: string, contents: string) => Promise<Result<void, string>>;
}

nodeFileSystemvalue

const nodeFileSystem: FileSystem

CliCommandtype

type CliCommand = {
    readonly kind: "init";
    readonly directory: string;
} | {
    readonly kind: "add-primitive";
    readonly directory: string;
    readonly type: string;
} | {
    readonly kind: "help";
};

CliErrortype

type CliError = {
    readonly code: "unknown-command";
    readonly given: string;
} | {
    readonly code: "missing-argument";
    readonly argument: string;
} | {
    readonly code: "unexpected-argument";
    readonly given: string;
} | {
    readonly code: "invalid-primitive-type";
    readonly type: string;
} | {
    readonly code: "reserved-primitive-type";
    readonly type: string;
} | {
    readonly code: "framework-namespace";
    readonly type: string;
} | {
    readonly code: "already-registered";
    readonly type: string;
} | {
    readonly code: "file-exists";
    readonly path: string;
} | {
    readonly code: "filesystem-failed";
    readonly path: string;
    readonly detail: string;
};

CliErrorCodetype

type CliErrorCode = CliError["code"];

CLI_ERROR_CODESvalue

Every way a command can refuse, in the order a user meets them.

const CLI_ERROR_CODES: readonly CliErrorCode[]

PlannedFiletype

type PlannedFile = {
    readonly path: string;
    readonly contents: string;
};

WritePlantype

type WritePlan = {
    readonly files: readonly PlannedFile[];
    /** Lines for the caller to print — what happened, and what to do next. */
    readonly notes: readonly string[];
};

PRIMITIVES_DIRECTORYvalue

const PRIMITIVES_DIRECTORY = "primitives"

existingPrimitivesfunction

The primitive modules already in the directory, recovered from their names.

const existingPrimitives: (paths: readonly string[]) => readonly PrimitiveNames[]

planCommandfunction

const planCommand: (command: CliCommand, existing: readonly string[]) => Result<WritePlan, CliError>

CLI_USAGEvalue

const CLI_USAGE = "loom \u2014 scaffolding for the Loom primitive registry\n\nUsage:\n  loom init [--dir <directory>]\n  loom add primitive <type> [--dir <directory>]\n  loom --help\n\nOptions:\n  --dir <directory>   Where the Loom source lives (default: loom)\n\ninit writes a starter primitive, a generated registry, and a conformance test\ninto <directory>/primitives. add primitive declares one more and\nregenerates the registry from the directory's contents.\n\nA type is dot-namespaced kebab-case: app.card, commerce.product-card.\nloom.* is the framework's own namespace and is refused \u2014 those\nnames belong to the primitives @jam-overture/loom already registers."

CliReporttype

type CliReport = {
    readonly written: readonly string[];
    readonly notes: readonly string[];
    readonly usage: boolean;
};

describeCliErrorfunction

const describeCliError: (error: CliError) => string

runClifunction

const runCli: (argv: readonly string[], filesystem: FileSystem) => Promise<Result<CliReport, CliError>>

PrimitiveNamestype

type PrimitiveNames = {
    /** The primitive type, exactly as a tree will address it. */
    readonly type: string;
    /**
     * The module basename, which is the type verbatim: `commerce.product-card.ts`.
     *
     * Dots survive where a slug would not. Folding `.` to `-` is lossy — nothing
     * can tell whether `commerce-product-card` was `commerce.product-card` or
     * `commerce-product.card` — and the registry is regenerated from the directory
     * listing, so that round trip has to be exact.
     */
    readonly module: string;
    /** The exported binding: `commerce.product-card` → `commerceProductCard`. */
    readonly exportName: string;
};

namesForfunction

const namesFor: (type: string) => PrimitiveNames

primitiveModulefunction

const primitiveModule: (names: PrimitiveNames) => string

REGISTRY_MODULEvalue

const REGISTRY_MODULE = "registry.ts"

CONFORMANCE_TEST_MODULEvalue

const CONFORMANCE_TEST_MODULE = "registry.test.ts"

RESERVED_PRIMITIVE_TYPESvalue

Reserved because the registry and its test share the primitives directory, and registry and registry.test are both valid primitive types — so a primitive named either one would be written over the file that registers it.

const RESERVED_PRIMITIVE_TYPES: readonly string[]

registryModulefunction

const registryModule: (primitives: readonly PrimitiveNames[]) => string

conformanceTestfunction

The generated test is the point of the generated scaffold. auditRegistry reports and never enforces, so a deployment only benefits from it if something actually runs it — and a host is far more likely to keep a test that was there from the first commit than to add one later.

const conformanceTest: () => string