@streetjs/storage 1.0.0

package/dist/cli/commands.js

@@ -0,0 +1,369 @@
+// src/cli/commands.ts
+// @streetjs/storage — CLI commands registered through the reused core CliKernel.
+//
+// Provides `make:storage`, `storage:list`, `storage:sync`, `storage:clean`,
+// `storage:migrate`, and `storage:verify` as `@Command`-decorated methods.
+//
+// `make:storage` delegates to the pure functions in `generators.ts`: it
+// validates the name before writing anything, refuses to overwrite an existing
+// target, and otherwise emits a typed scaffold that compiles under `tsc`
+// (Requirement 21.2). The operational commands build a configured
+// `Storage`/`StorageDriver` from CLI flags and act through the public facade
+// surface. `storage:verify` runs the shared contract-conformance suite against
+// the configured driver and reports pass/fail per check (Requirement 21.4).
+//
+// No class-level decorator is used, so no constructor dependency metadata is
+// emitted and the core `CliKernel` can `container.resolve` the class with no
+// registered dependencies. This mirrors the `@streetjs/events` cli/commands.ts
+// pattern.
+//
+// _Requirements: 21.1, 21.2, 21.3, 21.4_
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Command } from "streetjs";
+import { createStorage } from "../facade.js";
+import { MemoryStorageDriver } from "../drivers/memory.js";
+import { LocalStorageDriver } from "../drivers/local.js";
+import { StorageConfigError } from "../errors.js";
+import { runStorageDriverContract } from "../tests/contract.js";
+import { generateStorage, isValidGeneratorName, isValidProvider, writeScaffold, DEFAULT_STORAGE_DIR, } from "./generators.js";
+/**
+ * The set of `@Command`-decorated storage commands, registered through the core
+ * `CliKernel`. A plain class (no class-level decorator) so the kernel can
+ * `container.resolve` it without constructor dependency metadata.
+ */
+export class StorageCommands {
+    // ── make:storage ─────────────────────────────────────────────────────────
+    /**
+     * `street make:storage <Name> [--dir <dir>] [--provider memory|local]` —
+     * scaffold a typed storage module. Delegates to the pure generators: the name
+     * (and scaffold provider) are validated before any file is written, and an
+     * existing target is never overwritten (Requirement 21.2).
+     */
+    makeStorage(args) {
+        const name = this.resolveName(args);
+        if (!isValidGeneratorName(name)) {
+            console.error(`[storage] Invalid storage name: "${name}". ` +
+                `Use a PascalCase identifier (a letter followed by letters or digits).`);
+            process.exitCode = 1;
+            return;
+        }
+        const providerFlag = typeof args.flags["provider"] === "string" ? args.flags["provider"] : undefined;
+        let provider;
+        if (providerFlag !== undefined) {
+            if (!isValidProvider(providerFlag)) {
+                console.error(`[storage] Invalid scaffold provider: "${providerFlag}". ` +
+                    `Use a built-in zero-dependency provider ("memory" or "local").`);
+                process.exitCode = 1;
+                return;
+            }
+            provider = providerFlag;
+        }
+        const dir = typeof args.flags["dir"] === "string" ? args.flags["dir"] : DEFAULT_STORAGE_DIR;
+        let result;
+        try {
+            result = generateStorage(name, dir, provider);
+            writeScaffold(result);
+        }
+        catch (err) {
+            console.error(`[storage] ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`[storage] Generated storage module: ${result.path}`);
+    }
+    // ── storage:list ───────────────────────────────────────────────────────────
+    /**
+     * `street storage:list [<prefix>] [--provider memory|local] [--root <dir>]` —
+     * list the stored object keys for the configured driver. Builds a `Storage`
+     * from the CLI flags and prints every key under the prefix (Requirement 21.3).
+     */
+    async storageList(args) {
+        const prefix = this.resolvePrefix(args);
+        const storage = this.buildStorage(this.configFromArgs(args));
+        try {
+            const items = await storage.list(prefix);
+            if (items.length === 0) {
+                console.log(`[storage] No objects found under "${prefix}".`);
+            }
+            else {
+                for (const item of items) {
+                    console.log(item.key);
+                }
+                console.log(`[storage] ${items.length} object(s).`);
+            }
+        }
+        catch (err) {
+            console.error(`[storage] ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+        }
+        finally {
+            await this.closeQuietly(storage);
+        }
+    }
+    // ── storage:clean ────────────────────────────────────────────────────────────
+    /**
+     * `street storage:clean <prefix> [--provider memory|local] [--root <dir>]` —
+     * remove every object under a prefix from the configured driver. A prefix is
+     * required so the command never silently wipes an entire store; deletion of
+     * each object is isolated so one failure does not abort the rest
+     * (Requirement 21.3).
+     */
+    async storageClean(args) {
+        const prefix = this.resolvePrefix(args);
+        if (prefix === "") {
+            console.error(`[storage] storage:clean requires a non-empty prefix (refusing to remove every object). ` +
+                `Pass a prefix positionally or via --prefix.`);
+            process.exitCode = 1;
+            return;
+        }
+        const storage = this.buildStorage(this.configFromArgs(args));
+        let removed = 0;
+        try {
+            const items = await storage.list(prefix);
+            for (const item of items) {
+                try {
+                    await storage.delete(item.key);
+                    removed += 1;
+                }
+                catch (err) {
+                    console.error(`[storage] Failed to remove "${item.key}": ` +
+                        `${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            console.log(`[storage] Removed ${removed} object(s) under "${prefix}".`);
+        }
+        catch (err) {
+            console.error(`[storage] ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+        }
+        finally {
+            await this.closeQuietly(storage);
+        }
+    }
+    // ── storage:sync ─────────────────────────────────────────────────────────────
+    /**
+     * `street storage:sync [<prefix>] --from-provider <p> [--from-root <dir>]
+     * --to-provider <p> [--to-root <dir>]` — copy every object under a prefix from
+     * a source store to a destination store, leaving the source untouched
+     * (Requirement 21.3). Each object copy is isolated so a single failure does
+     * not abort the whole sync.
+     */
+    async storageSync(args) {
+        await this.transfer(args, { verb: "Synced" });
+    }
+    // ── storage:migrate ──────────────────────────────────────────────────────────
+    /**
+     * `street storage:migrate [<prefix>] --from-provider <p> [--from-root <dir>]
+     * --to-provider <p> [--to-root <dir>]` — move every object under a prefix from
+     * a source store to a destination store (copy, then remove from the source),
+     * so the destination becomes the new home for the data (Requirement 21.3).
+     * Each object migration is isolated so a single failure does not abort the
+     * whole migration.
+     */
+    async storageMigrate(args) {
+        await this.transfer(args, { removeSource: true, verb: "Migrated" });
+    }
+    // ── storage:verify ───────────────────────────────────────────────────────────
+    /**
+     * `street storage:verify [--provider memory|local] [--root <dir>]` — run the
+     * shared driver contract-conformance suite against the configured driver and
+     * report pass/fail per check, exiting non-zero when any check fails
+     * (Requirement 21.4).
+     */
+    async storageVerify(args) {
+        const config = this.configFromArgs(args);
+        let factory;
+        try {
+            factory = this.driverFactory(config);
+        }
+        catch (err) {
+            console.error(`[storage] ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+        const report = await runStorageDriverContract(factory);
+        console.log(`[storage] Contract conformance for driver "${report.driver}":`);
+        for (const result of report.results) {
+            const status = result.passed ? "PASS" : "FAIL";
+            console.log(`  [${status}] (${result.requirement}) ${result.name}`);
+            if (!result.passed && result.error !== undefined) {
+                console.log(`         ${result.error}`);
+            }
+        }
+        const passedCount = report.results.filter((r) => r.passed).length;
+        console.log(`[storage] ${passedCount}/${report.results.length} check(s) passed — ` +
+            `${report.passed ? "PASS" : "FAIL"}.`);
+        if (!report.passed) {
+            process.exitCode = 1;
+        }
+    }
+    // ── Shared helpers ───────────────────────────────────────────────────────────
+    /**
+     * Copy (and optionally remove-from-source) every object under a prefix from a
+     * source store to a destination store. Shared by `storage:sync` (copy) and
+     * `storage:migrate` (move). Every per-object transfer is isolated so one
+     * failure does not abort the rest.
+     */
+    async transfer(args, options) {
+        const prefix = this.resolvePrefix(args);
+        const source = this.buildStorage(this.transferConfig(args, "from"));
+        const destination = this.buildStorage(this.transferConfig(args, "to"));
+        let transferred = 0;
+        try {
+            const items = await source.list(prefix);
+            for (const item of items) {
+                try {
+                    const got = await source.get(item.key);
+                    if (!got.found || got.bytes === undefined) {
+                        continue;
+                    }
+                    const metadata = got.metadata;
+                    await destination.put(item.key, got.bytes, {
+                        contentType: metadata?.contentType,
+                        owner: metadata?.owner,
+                        tenant: metadata?.tenant,
+                        accessLevel: metadata?.accessLevel,
+                        custom: metadata?.custom,
+                    });
+                    if (options.removeSource === true) {
+                        await source.delete(item.key);
+                    }
+                    transferred += 1;
+                }
+                catch (err) {
+                    console.error(`[storage] Failed to transfer "${item.key}": ` +
+                        `${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            console.log(`[storage] ${options.verb} ${transferred} object(s) under "${prefix}".`);
+        }
+        catch (err) {
+            console.error(`[storage] ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+        }
+        finally {
+            await this.closeQuietly(source);
+            await this.closeQuietly(destination);
+        }
+    }
+    /** Build a live {@link Storage} facade from a resolved {@link StorageConfig}. */
+    buildStorage(config) {
+        return createStorage(config);
+    }
+    /**
+     * Resolve a {@link StorageConfig} from the CLI flags: `--provider` (defaults to
+     * `memory`) and `--root` (used by the `local` provider).
+     */
+    configFromArgs(args) {
+        const provider = typeof args.flags["provider"] === "string" ? args.flags["provider"] : "memory";
+        const root = typeof args.flags["root"] === "string" ? args.flags["root"] : undefined;
+        return { provider, root };
+    }
+    /**
+     * Resolve a source (`from`) or destination (`to`) {@link StorageConfig} from a
+     * prefixed pair of flags, e.g. `--from-provider`/`--from-root` and
+     * `--to-provider`/`--to-root`. Defaults to the `memory` provider.
+     */
+    transferConfig(args, side) {
+        const providerFlag = args.flags[`${side}-provider`];
+        const rootFlag = args.flags[`${side}-root`];
+        const provider = typeof providerFlag === "string" ? providerFlag : "memory";
+        const root = typeof rootFlag === "string" ? rootFlag : undefined;
+        return { provider, root };
+    }
+    /**
+     * Build a {@link StorageDriverFactory} for the configured driver, used by
+     * `storage:verify` to obtain a freshly constructed driver per contract check.
+     * A pre-constructed `config.driver` is returned as-is; the built-in `memory`
+     * and `local` providers are constructed fresh each call. An unknown provider
+     * with no supplied driver throws a descriptive {@link StorageConfigError}.
+     */
+    driverFactory(config) {
+        if (config.driver !== undefined) {
+            const driver = config.driver;
+            return () => driver;
+        }
+        if (config.provider === "memory") {
+            return () => new MemoryStorageDriver({ clock: config.clock });
+        }
+        if (config.provider === "local") {
+            if (config.root === undefined || config.root === "") {
+                throw new StorageConfigError('The "local" storage provider requires a "root" directory (pass --root <dir>).', { provider: "local" });
+            }
+            const root = config.root;
+            return () => new LocalStorageDriver({ root, clock: config.clock });
+        }
+        throw new StorageConfigError(`Unknown storage provider "${config.provider}". Provide a built-in provider ` +
+            `("memory" or "local"), or supply a pre-constructed "driver" for cloud providers.`, { provider: config.provider });
+    }
+    /** Read the generator name from the first positional arg or `--name`. */
+    resolveName(args) {
+        const positional = args.positional[0];
+        if (typeof positional === "string") {
+            return positional;
+        }
+        return typeof args.flags["name"] === "string" ? args.flags["name"] : "";
+    }
+    /** Read the key prefix from the first positional arg or `--prefix` (default ""). */
+    resolvePrefix(args) {
+        const positional = args.positional[0];
+        if (typeof positional === "string") {
+            return positional;
+        }
+        return typeof args.flags["prefix"] === "string" ? args.flags["prefix"] : "";
+    }
+    /** Close a storage facade, swallowing any error so cleanup never masks results. */
+    async closeQuietly(storage) {
+        try {
+            await storage.close();
+        }
+        catch {
+            // Ignore close failures during CLI cleanup.
+        }
+    }
+}
+__decorate([
+    Command("make:storage", "Scaffold a new storage module (make:storage <Name> [--dir <dir>] [--provider memory|local])"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], StorageCommands.prototype, "makeStorage", null);
+__decorate([
+    Command("storage:list", "List stored object keys for the configured driver (storage:list [<prefix>] [--provider <p>] [--root <dir>])"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], StorageCommands.prototype, "storageList", null);
+__decorate([
+    Command("storage:clean", "Remove all objects under a prefix (storage:clean <prefix> [--provider <p>] [--root <dir>])"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], StorageCommands.prototype, "storageClean", null);
+__decorate([
+    Command("storage:sync", "Copy objects between two configured stores (storage:sync [<prefix>] --from-provider <p> --to-provider <p>)"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], StorageCommands.prototype, "storageSync", null);
+__decorate([
+    Command("storage:migrate", "Migrate objects from one store to another (storage:migrate [<prefix>] --from-provider <p> --to-provider <p>)"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], StorageCommands.prototype, "storageMigrate", null);
+__decorate([
+    Command("storage:verify", "Run the contract-conformance suite against the configured driver (storage:verify [--provider <p>] [--root <dir>])"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], StorageCommands.prototype, "storageVerify", null);
+//# sourceMappingURL=commands.js.map

package/dist/cli/commands.js.map

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

package/dist/cli/generators.d.ts

@@ -0,0 +1,41 @@
+/** The outcome of a generator invocation. */
+export interface GenerateResult {
+    /** Path of the file that was (or would be) written. */
+    path: string;
+    /** The generated source content. */
+    contents: string;
+}
+/** Default output directory for `make:storage` scaffolds. */
+export declare const DEFAULT_STORAGE_DIR = "./storage";
+/** The built-in, zero-dependency providers a scaffold may target directly. */
+declare const BUILT_IN_PROVIDERS: readonly ["memory", "local"];
+/** A zero-dependency provider name accepted by {@link generateStorage}. */
+export type BuiltInProvider = (typeof BUILT_IN_PROVIDERS)[number];
+/** Validate a `make:storage` name (identifier-safe). */
+export declare function isValidGeneratorName(name: string): boolean;
+/** Validate a scaffold provider against the built-in zero-dependency set. */
+export declare function isValidProvider(provider: string): provider is BuiltInProvider;
+/**
+ * Generate a storage module scaffold: a typed factory that builds a
+ * {@link Storage} instance through {@link createStorage}, importing only the
+ * public `@streetjs/storage` surface. Compiles cleanly under `tsc`
+ * (Requirement 21.2).
+ *
+ * @param name - PascalCase identifier for the storage module.
+ * @param dir - Output directory (defaults to {@link DEFAULT_STORAGE_DIR}).
+ * @param provider - A built-in zero-dependency provider (`memory` or `local`);
+ *   defaults to `memory` so the scaffold runs without configuration.
+ * @throws Error when `name` is not a valid identifier or `provider` is not a
+ *   built-in zero-dependency provider — validated before any output is produced.
+ */
+export declare function generateStorage(name: string, dir?: string, provider?: BuiltInProvider): GenerateResult;
+/**
+ * Write a generated scaffold to disk, refusing to overwrite an existing target
+ * and creating a fresh file otherwise. The parent directory is created as
+ * needed; the `wx` flag makes the no-overwrite check atomic.
+ *
+ * @throws Error when the target file already exists.
+ */
+export declare function writeScaffold(result: GenerateResult): void;
+export {};
+//# sourceMappingURL=generators.d.ts.map

package/dist/cli/generators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/cli/generators.ts"],"names":[],"mappings":"AAeA,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C,8EAA8E;AAC9E,QAAA,MAAM,kBAAkB,8BAA+B,CAAC;AAExD,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,wDAAwD;AACxD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,eAAe,CAE7E;AAsCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAA4B,EACjC,QAAQ,GAAE,eAA0B,GACnC,cAAc,CAoChB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAM1D"}

package/dist/cli/generators.js

@@ -0,0 +1,119 @@
+// src/cli/generators.ts
+// @streetjs/storage — code generators for `make:storage`.
+//
+// Validate a name, refuse to overwrite an existing target, and emit a typed
+// scaffold that imports only public `@streetjs/storage` symbols and compiles
+// under `tsc`. Name validation and template rendering are pure (no filesystem),
+// so they are trivially unit-testable; `writeScaffold` performs the guarded
+// write. This mirrors the `@streetjs/events` cli/generators.ts pattern.
+//
+// Requirement 21.2: `make:storage` produces TypeScript source that compiles
+// with `tsc` without errors.
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** A generator name must be an identifier-safe PascalCase token. */
+const IDENTIFIER_RE = /^[A-Za-z][A-Za-z0-9]*$/;
+/** Default output directory for `make:storage` scaffolds. */
+export const DEFAULT_STORAGE_DIR = "./storage";
+/** The built-in, zero-dependency providers a scaffold may target directly. */
+const BUILT_IN_PROVIDERS = ["memory", "local"];
+/** Validate a `make:storage` name (identifier-safe). */
+export function isValidGeneratorName(name) {
+    return typeof name === "string" && IDENTIFIER_RE.test(name);
+}
+/** Validate a scaffold provider against the built-in zero-dependency set. */
+export function isValidProvider(provider) {
+    return BUILT_IN_PROVIDERS.includes(provider);
+}
+function toClassName(name) {
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function assertValidName(name) {
+    if (!isValidGeneratorName(name)) {
+        throw new Error(`Invalid generator name: "${name}". Use a PascalCase identifier ` +
+            `(a letter followed by letters or digits, e.g. "Uploads").`);
+    }
+}
+function assertValidProvider(provider) {
+    if (!isValidProvider(provider)) {
+        throw new Error(`Invalid storage provider: "${provider}". Use a built-in zero-dependency ` +
+            `provider (${BUILT_IN_PROVIDERS.map((p) => `"${p}"`).join(" or ")}).`);
+    }
+}
+/**
+ * Render the provider-specific `StorageConfig` literal body. The `local`
+ * provider requires a `root` directory, so the scaffold supplies a sensible
+ * default that keeps the emitted module compiling and runnable out of the box.
+ */
+function renderConfigBody(provider, className) {
+    if (provider === "local") {
+        return `    provider: "local",
+    // The local filesystem driver persists objects beneath this directory.
+    root: "./var/${className.toLowerCase()}",`;
+    }
+    return `    provider: "memory",`;
+}
+/**
+ * Generate a storage module scaffold: a typed factory that builds a
+ * {@link Storage} instance through {@link createStorage}, importing only the
+ * public `@streetjs/storage` surface. Compiles cleanly under `tsc`
+ * (Requirement 21.2).
+ *
+ * @param name - PascalCase identifier for the storage module.
+ * @param dir - Output directory (defaults to {@link DEFAULT_STORAGE_DIR}).
+ * @param provider - A built-in zero-dependency provider (`memory` or `local`);
+ *   defaults to `memory` so the scaffold runs without configuration.
+ * @throws Error when `name` is not a valid identifier or `provider` is not a
+ *   built-in zero-dependency provider — validated before any output is produced.
+ */
+export function generateStorage(name, dir = DEFAULT_STORAGE_DIR, provider = "memory") {
+    // Validate every input BEFORE producing any output (pure, no filesystem).
+    assertValidName(name);
+    assertValidProvider(provider);
+    const className = toClassName(name);
+    const factoryName = `create${className}Storage`;
+    const configName = `${className.charAt(0).toLowerCase()}${className.slice(1)}StorageConfig`;
+    const path = join(dir, `${className}Storage.ts`);
+    const contents = `// ${className}Storage.ts — generated by \`street make:storage ${name}\`.
+import { createStorage } from "@streetjs/storage";
+import type { Storage, StorageConfig } from "@streetjs/storage";
+
+/**
+ * Configuration for the ${className} storage module. Backed by the built-in
+ * zero-dependency "${provider}" provider so it runs without external services.
+ * Switch \`provider\` (and supply a pre-constructed \`driver\` for cloud
+ * providers) to change the backend without touching call sites.
+ */
+export const ${configName}: StorageConfig = {
+${renderConfigBody(provider, className)}
+};
+
+/**
+ * Build the ${className} {@link Storage} instance. Application code should call
+ * this once during startup and share the returned facade.
+ *
+ * Use it:
+ *   const storage = ${factoryName}();
+ *   await storage.put("hello.txt", "world");
+ */
+export function ${factoryName}(): Storage {
+  return createStorage(${configName});
+}
+`;
+    return { path, contents };
+}
+/**
+ * Write a generated scaffold to disk, refusing to overwrite an existing target
+ * and creating a fresh file otherwise. The parent directory is created as
+ * needed; the `wx` flag makes the no-overwrite check atomic.
+ *
+ * @throws Error when the target file already exists.
+ */
+export function writeScaffold(result) {
+    if (existsSync(result.path)) {
+        throw new Error(`Refusing to overwrite existing file: ${result.path}`);
+    }
+    mkdirSync(dirname(result.path), { recursive: true });
+    writeFileSync(result.path, result.contents, { encoding: "utf8", flag: "wx" });
+}
+//# sourceMappingURL=generators.js.map

package/dist/cli/generators.js.map

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

package/dist/directory.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @streetjs/storage — the Directory API over a flat key space (task 17.1).
+ *
+ * Object stores have a flat key space with no real directories. This module
+ * implements a directory-style API entirely over that flat key space using
+ * `/`-delimited prefixes, so the same code runs unchanged on every
+ * {@link StorageDriver} — including prefix-only cloud providers (Requirement
+ * 15.5). The facade exposes the constructed instance as `storage.directory`.
+ *
+ * The four operations map onto driver primitives (`list`/`put`/`delete`) as
+ * follows:
+ *
+ * - `mkdir(path)` records an empty marker key `path/`, making the path
+ *   available as a directory prefix (Requirement 15.1). A root/empty path needs
+ *   no marker and is a no-op.
+ * - `listDirectory(path)` calls `driver.list(path/)` and collapses the results
+ *   to the **immediate** children by splitting each key on the next `/` after
+ *   the prefix: keys with no further `/` are file entries, keys with a further
+ *   `/` contribute a single synthesized sub-directory entry (Requirement 15.2).
+ * - `removeDirectory(path)` deletes every key under the prefix; when the prefix
+ *   contains no objects it is a success no-op that removes nothing
+ *   (Requirements 15.3, 15.6).
+ * - `walk(path)` returns every object key strictly beneath the prefix
+ *   (Requirement 15.4).
+ *
+ * The public {@link DirectoryApi} type is owned by `facade.ts` (and re-exported
+ * from `index.ts`); it is imported here type-only so there is no runtime import
+ * cycle between the two modules.
+ *
+ * _Requirements: 15.1, 15.2, 15.3, 15.4, 15.5, 15.6_
+ */
+import type { StorageDriver } from "./driver.js";
+import type { DirectoryApi } from "./facade.js";
+import type { StorageListItem } from "./types.js";
+/**
+ * A {@link DirectoryApi} implementation over any {@link StorageDriver}'s flat
+ * key space. It holds only the driver and derives every directory operation
+ * from `/`-delimited prefixes, so it behaves identically across providers.
+ */
+export declare class StorageDirectoryApi implements DirectoryApi {
+    private readonly driver;
+    constructor(driver: StorageDriver);
+    /**
+     * Normalize a directory `path` to a prefix ending in the delimiter. The root
+     * (`""` or `"/"`) normalizes to the empty prefix (which matches every key),
+     * and any leading delimiter is dropped so `"/photos"` and `"photos"` refer to
+     * the same directory. A path that already ends with the delimiter is left
+     * unchanged.
+     */
+    private toPrefix;
+    /**
+     * List the keys stored under `prefix`, defensively re-filtering by the prefix
+     * so drivers that interpret `list` loosely never leak keys from outside the
+     * directory into a directory operation.
+     */
+    private keysUnder;
+    /**
+     * Make `path` available as a directory prefix by recording an empty marker
+     * key `path/` (Requirement 15.1). The root/empty path requires no marker and
+     * is a no-op.
+     */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Return the immediate child entries under `path` (Requirement 15.2). Each
+     * key under the prefix is split on the next delimiter: a key with no further
+     * delimiter is returned as its file entry; keys sharing a further path
+     * segment collapse into a single synthesized sub-directory entry (key
+     * `path/child/`, `size` 0). The directory's own marker (a key equal to the
+     * prefix) is not reported as a child.
+     */
+    listDirectory(path: string): Promise<StorageListItem[]>;
+    /**
+     * Remove every object stored under `path` (Requirement 15.3). When the prefix
+     * contains no objects — because the directory does not exist or is already
+     * empty — nothing is removed and a success result of `{ removed: false }` is
+     * returned without throwing (Requirement 15.6). When at least one object is
+     * removed the result is `{ removed: true }`.
+     */
+    removeDirectory(path: string): Promise<{
+        readonly removed: boolean;
+    }>;
+    /**
+     * Return every object key strictly beneath `path` (Requirement 15.4),
+     * excluding the directory's own marker key (a key equal to the prefix).
+     */
+    walk(path: string): Promise<string[]>;
+}
+//# sourceMappingURL=directory.d.ts.map

package/dist/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAKlD;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,MAAM,EAAE,aAAa;IAIjC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAWhB;;;;OAIG;YACW,SAAS;IAQvB;;;;OAIG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;;;;;;OAOG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IA+B7D;;;;;;OAMG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAY3E;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAK5C"}