@stringsync/splates 0.0.61 → 1.13.3

package/vendor/core/cmd/index.js

@@ -0,0 +1,477 @@
+// cmd/cli.ts
+import { ConsoleLogger, color as color3 } from "../log/index.js";
+import { NodePs } from "../system/index.js";
+
+// cmd/command.ts
+import { color as color2 } from "../log/index.js";
+
+// cmd/help.ts
+import { color } from "../log/index.js";
+var INDENT = "  ";
+var GAP = "  ";
+var MIN_BESIDE = 30;
+var UNDER = "    ";
+function table(rows, style, width) {
+  const pad = Math.max(0, ...rows.map(([label]) => label.length));
+  const column = INDENT.length + pad + GAP.length;
+  const beside = width === undefined || width - column >= MIN_BESIDE;
+  const laid = rows.map(([label, text]) => {
+    if (!text) {
+      return [`${INDENT}${style(label)}`];
+    }
+    if (beside) {
+      const [first, ...rest] = wrap(text, width && width - column);
+      return [
+        `${INDENT}${style(label.padEnd(pad))}${GAP}${first}`,
+        ...rest.map((line) => `${" ".repeat(column)}${line}`)
+      ];
+    }
+    const indent = `${INDENT}${UNDER}`;
+    return [
+      `${INDENT}${style(label)}`,
+      ...wrap(text, width && width - indent.length).map((line) => `${indent}${line}`)
+    ];
+  });
+  const parted = laid.some((lines) => lines.length > 1);
+  return laid.flatMap((lines, i) => parted && i > 0 ? ["", ...lines] : lines);
+}
+function wrap(text, width) {
+  if (width === undefined) {
+    return text.split(`
+`);
+  }
+  const lines = [];
+  for (const paragraph of text.split(`
+`)) {
+    let line = [];
+    let length = 0;
+    for (const word of paragraph.split(" ")) {
+      const size = color.strip(word).length;
+      if (line.length > 0 && length + 1 + size > width) {
+        lines.push(line.join(" "));
+        line = [];
+        length = 0;
+      }
+      length += (line.length > 0 ? 1 : 0) + size;
+      line.push(word);
+    }
+    lines.push(line.join(" "));
+  }
+  return lines;
+}
+
+// cmd/middleware.ts
+function compose(middleware, action) {
+  return middleware.reduceRight((next, mw) => (ctx) => mw(ctx, next), action);
+}
+
+// cmd/command.ts
+class Command {
+  name;
+  _description = "";
+  options = [];
+  args = [];
+  variadic;
+  middleware = [];
+  _action = () => {};
+  hasAction = false;
+  unknownOptions = false;
+  excessArguments = false;
+  passThrough = false;
+  constructor(name) {
+    this.name = name;
+  }
+  description(description) {
+    this._description = description;
+    return this;
+  }
+  summary() {
+    return this._description;
+  }
+  option(name, schema, meta) {
+    this.options.push({
+      name,
+      schema,
+      description: meta?.description,
+      hasDefault: meta !== undefined && "default" in meta,
+      default: meta?.default,
+      isSwitch: takesBooleans(schema)
+    });
+    return this;
+  }
+  repeated(name, schema, meta) {
+    this.options.push({
+      name,
+      schema,
+      description: meta?.description,
+      hasDefault: false,
+      isSwitch: false,
+      repeated: true
+    });
+    return this;
+  }
+  arg(name, schema, meta) {
+    if (this.variadic) {
+      throw new Error(`${this.name}: ${this.variadic.name} takes every remaining argument, so ${name} would never be filled`);
+    }
+    this.args.push({
+      name,
+      schema,
+      description: meta?.description,
+      hasDefault: meta !== undefined && "default" in meta,
+      default: meta?.default,
+      isSwitch: false
+    });
+    return this;
+  }
+  rest(name, schema, meta) {
+    if (this.variadic) {
+      throw new Error(`${this.name}: ${this.variadic.name} already takes every remaining argument`);
+    }
+    this.variadic = {
+      name,
+      schema,
+      description: meta?.description,
+      hasDefault: false,
+      isSwitch: false
+    };
+    return this;
+  }
+  allowUnknownOption(allow = true) {
+    this.unknownOptions = allow;
+    return this;
+  }
+  allowExcessArguments(allow = true) {
+    this.excessArguments = allow;
+    return this;
+  }
+  passThroughOptions(passThrough = true) {
+    this.passThrough = passThrough;
+    return this;
+  }
+  use(middleware) {
+    if (this.hasAction) {
+      throw new Error(`${this.name}: use() must come before action()`);
+    }
+    this.middleware.push(middleware);
+    return this;
+  }
+  action(action) {
+    this._action = action;
+    this.hasAction = true;
+    return this;
+  }
+  exec(argv, deps, outer = [], path = this.name) {
+    if (this.wantsHelp(argv)) {
+      this.help(deps.log, path, deps.ps?.columns());
+      return;
+    }
+    const opts = this.parse(argv);
+    const chain = [...outer, ...this.middleware];
+    if (chain.length === 0) {
+      return this._action(opts, deps);
+    }
+    let result;
+    const run = compose(chain, async (ctx) => {
+      result = await this._action(opts, ctx);
+    });
+    return run(deps).then(() => result);
+  }
+  wantsHelp(argv) {
+    for (let i = 0;i < argv.length; i++) {
+      const token = argv[i];
+      if (token === "--") {
+        return false;
+      }
+      if (token === "--help" || token === "-h") {
+        return true;
+      }
+      if (this.passThrough && token !== undefined && !this.isValue(argv, i)) {
+        return false;
+      }
+    }
+    return false;
+  }
+  isValue(argv, i) {
+    const token = argv[i];
+    if (token?.startsWith("-")) {
+      return true;
+    }
+    const previous = argv[i - 1];
+    if (previous === undefined || !previous.startsWith("--")) {
+      return false;
+    }
+    return !previous.includes("=") && !this.isSwitch(previous.slice(2));
+  }
+  isSwitch(name) {
+    return this.options.some((option) => option.name === name && option.isSwitch);
+  }
+  parse(argv) {
+    const raw = new Map;
+    const repeats = new Map;
+    const give = (option, value) => option.repeated ? repeats.set(option.name, [...repeats.get(option.name) ?? [], value]) : raw.set(option.name, value);
+    const positional = [];
+    for (let i = 0;i < argv.length; i++) {
+      const token = argv[i];
+      if (token === undefined) {
+        continue;
+      }
+      if (token === "--") {
+        positional.push(...argv.slice(i + 1));
+        break;
+      }
+      const stopped = this.passThrough && positional.length > 0;
+      if (!token.startsWith("--") || stopped) {
+        positional.push(token);
+        continue;
+      }
+      const eq = token.indexOf("=");
+      const name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+      const option = this.options.find((option) => option.name === name);
+      if (option === undefined) {
+        if (!this.unknownOptions) {
+          throw new Error(`unknown option --${name}`);
+        }
+        positional.push(token);
+        continue;
+      }
+      if (eq !== -1) {
+        give(option, token.slice(eq + 1));
+      } else {
+        const next = argv[i + 1];
+        if (!option.isSwitch && next !== undefined && !next.startsWith("--")) {
+          give(option, next);
+          i++;
+        } else {
+          give(option, "true");
+        }
+      }
+    }
+    const extra = positional[this.args.length];
+    if (extra !== undefined && !this.variadic && !this.excessArguments) {
+      throw new Error(`unexpected argument "${extra}"`);
+    }
+    const out = {};
+    this.args.forEach((arg, i) => {
+      const value = positional[i];
+      if (value === undefined) {
+        if (arg.hasDefault) {
+          out[arg.name] = arg.default;
+          return;
+        }
+        const missing = absent(arg.schema);
+        if (missing !== null) {
+          out[arg.name] = missing.value;
+          return;
+        }
+        throw new Error(`missing required argument <${arg.name}>`);
+      }
+      out[arg.name] = read(arg.schema, value);
+    });
+    if (this.variadic) {
+      const rest = this.variadic;
+      out[rest.name] = positional.slice(this.args.length).map((value) => read(rest.schema, value));
+    }
+    for (const opt of this.options) {
+      if (opt.repeated) {
+        out[opt.name] = (repeats.get(opt.name) ?? []).map((value) => read(opt.schema, value));
+        continue;
+      }
+      const value = raw.get(opt.name);
+      if (value === undefined) {
+        if (opt.hasDefault) {
+          out[opt.name] = opt.default;
+          continue;
+        }
+        const missing = absent(opt.schema);
+        if (missing !== null) {
+          out[opt.name] = missing.value;
+          continue;
+        }
+        if (opt.isSwitch) {
+          out[opt.name] = false;
+          continue;
+        }
+        throw new Error(`missing required option --${opt.name}`);
+      }
+      out[opt.name] = read(opt.schema, opt.isSwitch ? onOff(opt.name, value) : value);
+    }
+    return out;
+  }
+  optionRow(option) {
+    const defaultDescription = option.hasDefault && option.default !== undefined ? color2.dim(` (default: ${JSON.stringify(option.default)})`) : "";
+    return [
+      `--${option.name}`,
+      `${option.description ?? ""}${defaultDescription}`
+    ];
+  }
+  help(log, path, width) {
+    const args = this.args.map((arg) => arg.hasDefault ? `[${arg.name}]` : `<${arg.name}>`);
+    if (this.variadic) {
+      args.push(`[${this.variadic.name}...]`);
+    }
+    const usage = [
+      color2.bold(path),
+      color2.dim([...args, "[options]"].join(" "))
+    ].join(" ");
+    const lines = [`${color2.bold("Usage:")} ${usage}`];
+    if (this._description) {
+      lines.push("", ...wrap(this._description, width));
+    }
+    const named = this.variadic ? [...this.args, { ...this.variadic, name: `${this.variadic.name}...` }] : this.args;
+    if (named.length > 0) {
+      lines.push("", color2.bold("Arguments:"), ...table(named.map((arg) => [arg.name, arg.description ?? ""]), color2.blue, width));
+    }
+    lines.push("", color2.bold("Options:"));
+    const rows = [
+      ...this.options.map((option) => this.optionRow(option)),
+      ["-h, --help", "show this help"]
+    ];
+    lines.push(...table(rows, color2.blue, width));
+    log.info(lines.join(`
+`));
+  }
+}
+function read(schema, raw) {
+  const result = schema["~standard"].validate(raw);
+  if (result instanceof Promise) {
+    throw new Error(`${schema["~standard"].vendor} validated asynchronously, which is not supported here`);
+  }
+  if (result.issues === undefined) {
+    return result.value;
+  }
+  const issue = result.issues[0];
+  const path = (issue?.path ?? []).map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
+  const message = issue?.message ?? "invalid";
+  throw new Error(path ? `${path}: ${message}` : message);
+}
+function takesBooleans(schema) {
+  const keeps = (value) => {
+    const result = schema["~standard"].validate(value);
+    if (result instanceof Promise) {
+      result.catch(() => {});
+      return false;
+    }
+    return result.issues === undefined && result.value === value;
+  };
+  return keeps(true) && keeps(false) && !keeps("true");
+}
+function onOff(name, raw) {
+  if (raw !== "true" && raw !== "false") {
+    throw new Error(`--${name}: expected true or false, got "${raw}"`);
+  }
+  return raw === "true";
+}
+function absent(schema) {
+  const result = schema["~standard"].validate(undefined);
+  if (result instanceof Promise || result.issues !== undefined) {
+    return null;
+  }
+  return { value: result.value };
+}
+
+// cmd/cli.ts
+class Cli {
+  name;
+  cmds = new Map;
+  middleware = [];
+  _description = "";
+  _fallback;
+  constructor(name) {
+    this.name = name;
+  }
+  description(description) {
+    this._description = description;
+    return this;
+  }
+  use(middleware) {
+    if (this.cmds.size > 0) {
+      throw new Error(`${this.name}: use() must come before command()`);
+    }
+    this.middleware.push(middleware);
+    return this;
+  }
+  command(name) {
+    const command = new Command(name);
+    this.cmds.set(name, command);
+    return command;
+  }
+  group(name) {
+    const group = new Cli(name);
+    this.cmds.set(name, group);
+    return group;
+  }
+  fallback(name) {
+    this._fallback = name;
+    return this;
+  }
+  mount(name, sub) {
+    this.cmds.set(name, sub);
+    return this;
+  }
+  run(deps, argv) {
+    const ps = deps.ps ?? new NodePs;
+    const full = { ...deps, log: deps.log ?? new ConsoleLogger, ps };
+    try {
+      const out = this.exec(argv ?? ps.args, full, []);
+      return out instanceof Promise ? out.catch((error) => this.fail(full, error)) : out;
+    } catch (error) {
+      return this.fail(full, error);
+    }
+  }
+  exec(argv, deps, outer = [], path = this.name) {
+    const [name, ...rest] = argv;
+    if (name === "--help" || name === "-h") {
+      return this.help(deps, path);
+    }
+    const cmd = name === undefined ? undefined : this.cmds.get(name);
+    if (!cmd) {
+      const fallback = this._fallback === undefined ? undefined : this.cmds.get(this._fallback);
+      return fallback ? fallback.exec(argv, deps, [...outer, ...this.middleware], path) : this.help(deps, path);
+    }
+    return cmd.exec(rest, deps, [...outer, ...this.middleware], `${path} ${name}`);
+  }
+  summary() {
+    return this._description;
+  }
+  fail(deps, error) {
+    deps.log.error(`error: ${error instanceof Error ? error.message : error}`);
+    deps.ps.exit(1);
+  }
+  help(deps, path) {
+    const rows = [...this.cmds].map(([name, command]) => {
+      const fallback = name === this._fallback ? color3.dim("(default)") : "";
+      return [name, [command.summary(), fallback].filter(Boolean).join(" ")];
+    });
+    const lines = [
+      `${color3.bold("Usage:")} ${color3.bold(path)} ${color3.dim("<command> [options]")}`,
+      "",
+      color3.bold("Commands:"),
+      ...table(rows, (name) => color3.bold(color3.blue(name)), deps.ps.columns()),
+      "",
+      color3.dim(`Run \`${path} <command> --help\` for a command's options.`)
+    ];
+    deps.log.info(lines.join(`
+`));
+  }
+}
+function cli(name) {
+  return new Cli(name);
+}
+// cmd/timed.ts
+import { color as color4 } from "../log/index.js";
+import { Stopwatch, SystemClock } from "../time/index.js";
+function timed(clock = new SystemClock) {
+  return async (ctx, next) => {
+    const stopwatch = new Stopwatch(clock);
+    stopwatch.start();
+    ctx.ps.once("exit", () => {
+      ctx.log.error(color4.dim(`done in ${stopwatch.elapsed().human()}`));
+    });
+    await next(ctx);
+  };
+}
+export {
+  cli,
+  timed
+};

package/vendor/core/cmd/middleware.d.ts

@@ -0,0 +1,15 @@
+/** Runs whatever is left of the chain, with the context it should see. */
+export type Next<C> = (ctx: C) => Promise<void>;
+/**
+ * Wraps an action: do some work, hand a context to `next`, and do more once it
+ * comes back. `Out` is what everything downstream sees, so a middleware that
+ * contributes to the context widens its type as well as its value.
+ *
+ * Middleware runs after `--help` and after options are parsed, so it only ever
+ * wraps the action itself: asking for help never pays for the setup.
+ */
+export type Middleware<In, Out = In> = (ctx: In, next: Next<Out>) => Promise<void>;
+/** A middleware of any context types, as a chain holds it. */
+export type AnyMiddleware = Middleware<never, never>;
+/** Folds a chain into one call, innermost last. */
+export declare function compose(middleware: AnyMiddleware[], action: (ctx: unknown) => Promise<void>): (ctx: unknown) => Promise<void>;

package/vendor/core/cmd/timed.d.ts

@@ -0,0 +1,15 @@
+import { type Clock } from "../time/index.js";
+import type { Deps } from "./deps";
+import type { Middleware } from "./middleware";
+/**
+ * Says how long a command took, on stderr, as the process ends. That is
+ * after the action returns, or whenever something ends the process sooner,
+ * since a command that sets its exit code with `ps.exit` never returns to a
+ * middleware to report it.
+ *
+ * ```ts
+ * program.command("check").use(timed()).action(...);
+ * // ... done in 1m 12s
+ * ```
+ */
+export declare function timed<C extends Deps>(clock?: Clock): Middleware<C>;

package/vendor/core/creds/credential-proxy.d.ts

@@ -0,0 +1,55 @@
+import type { AsyncResource } from "../disposable/index.js";
+import type { CredentialSource } from "./credential-source";
+/** What `CredentialProxy.listen` forwards, and which key it puts in. */
+export interface CredentialProxyOptions {
+    /**
+     * Where every request goes: an `https://` origin, with a path each
+     * request's own is put under when it has one, such as
+     * `https://api.openai.com/v1`. Nothing else is ever reached.
+     */
+    upstream: string;
+    /** The credential's name in the source, such as `ANTHROPIC_API_KEY`. */
+    credential: string;
+    /**
+     * The header the key travels in, such as `x-api-key` for Anthropic or
+     * `authorization` for OpenAI. The client sends its placeholder there, and
+     * the proxy puts the real key there in its place.
+     */
+    header: string;
+    /** The word before the key in that header, such as `Bearer`; none by default. */
+    scheme?: string;
+}
+/**
+ * A loopback HTTP proxy that keeps an API key from the program it serves,
+ * such as an agent's CLI. The program gets `url` as its provider's base URL
+ * and `placeholder` as its key; the proxy forwards each of its requests to
+ * the one upstream with the placeholder swapped for the real key, which it
+ * reads from its source on every request, so a rotated key needs no
+ * restart. The program never holds the key, so it cannot print, log or send
+ * it anywhere.
+ *
+ * It listens on 127.0.0.1 alone, on a free port, and refuses with a 401,
+ * reaching no upstream, any request without its own placeholder, which is
+ * random for each proxy, so another local process, or another task's agent,
+ * cannot spend the key through it. It never follows a redirect, so the key
+ * goes to the upstream origin and nowhere else, and it passes responses
+ * through as they stream, server-sent events and compressed bodies alike.
+ * No response, error or log of its own ever holds the key.
+ *
+ * The placeholder is only as private as the program's environment: on a
+ * machine where the program runs as the proxy's own user, make the process
+ * holding the key undumpable (`makeUndumpable()` from `webappwiz/system`),
+ * or run the program in a container.
+ */
+export declare class CredentialProxy implements AsyncResource {
+    private readonly server;
+    /** The base URL to hand the program, as `http://127.0.0.1:<port>`. */
+    readonly url: string;
+    /** The key to hand the program in place of the real one. */
+    readonly placeholder: string;
+    private constructor();
+    /** Starts a proxy for one credential, reading it from `source`. */
+    static listen(source: CredentialSource, opts: CredentialProxyOptions): CredentialProxy;
+    /** Stops listening and cuts every request still streaming. */
+    disposeAsync(): Promise<void>;
+}

package/vendor/core/creds/credential-source.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Somewhere a credential's value can come from, by its environment variable
+ * name. `Credentials` reads a list of them in order, and the caller picks
+ * which: the environment and a `.env` file where the app is deployed, the
+ * system's store on a person's machine.
+ */
+export interface CredentialSource {
+    /** What a person calls it, as in "the environment" or "the macOS Keychain". */
+    readonly label: string;
+    /** The value it has for `name`, or undefined when it has none. */
+    get(name: string): Promise<string | undefined>;
+}
+/**
+ * `name`, when it can be an environment variable's: letters, digits and
+ * `_`, not starting with a digit. Throws otherwise, so a store never keeps a
+ * value no environment could hold, and its own bookkeeping, under names
+ * that cannot be these, is safe from a credential's.
+ */
+export declare function credentialName(name: string): string;

package/vendor/core/creds/credentials.d.ts

@@ -0,0 +1,28 @@
+import type { CredentialSource } from "./credential-source";
+/**
+ * An app's credentials, each named the way its environment variable is, read
+ * from the sources the caller lists, first one with a value wins. Which
+ * sources is the caller's choice: the environment and a `.env` file where the
+ * app is deployed, only the system's store on a person's machine, so a stray
+ * export or a forgotten `.env` is never what a dev run reads. A source need
+ * not list what it holds, so a caller names what it needs; a `SecretStore`
+ * can also list its own.
+ *
+ * It is a source itself, so lists compose: a group of sources is one entry
+ * in another list, and any object with a `label` and a `get`, such as one
+ * over a hosted secrets manager, is a source too.
+ */
+export declare class Credentials implements CredentialSource {
+    readonly sources: readonly CredentialSource[];
+    readonly label: string;
+    constructor(sources: readonly CredentialSource[]);
+    /** The value of `name`, or undefined when no source has it. */
+    get(name: string): Promise<string | undefined>;
+    /**
+     * The value of `name`, or an error saying where it looked. The error never
+     * holds a value, so it is safe to show anyone.
+     */
+    require(name: string): Promise<string>;
+    /** The source `name` would be read from, without reading it out; undefined when none has it. */
+    source(name: string): Promise<CredentialSource | undefined>;
+}

package/vendor/core/creds/dotenv-file.d.ts

@@ -0,0 +1,22 @@
+import { type Fs } from "../system/index.js";
+import type { CredentialSource } from "./credential-source";
+/** Where `DotenvFile` reads; the real filesystem by default. */
+export interface DotenvFileOptions {
+    fs?: Fs;
+}
+/**
+ * A `.env` file of `NAME=value` lines, read once, on the first `get`. A
+ * missing file has nothing, rather than failing, so a deploy without one
+ * falls through to the next source. Values may be quoted, a line may start
+ * with `export`, and `#` starts a comment outside quotes. Variables are not
+ * expanded.
+ */
+export declare class DotenvFile implements CredentialSource {
+    readonly path: string;
+    readonly label: string;
+    private fs;
+    private values?;
+    constructor(path: string, opts?: DotenvFileOptions);
+    get(name: string): Promise<string | undefined>;
+    private read;
+}

package/vendor/core/creds/environment.d.ts

@@ -0,0 +1,18 @@
+import { type Ps } from "../system/index.js";
+import type { CredentialSource } from "./credential-source";
+/** Where `Environment` reads; the real process by default. */
+export interface EnvironmentOptions {
+    ps?: Ps;
+}
+/**
+ * The process's environment variables, the way CI, containers and hosting
+ * platforms hand a deployed app its secrets. An empty value counts as none.
+ * Bun loads a project's `.env` files into the environment itself, so under
+ * Bun this reads them too.
+ */
+export declare class Environment implements CredentialSource {
+    readonly label = "the environment";
+    private ps;
+    constructor(opts?: EnvironmentOptions);
+    get(name: string): Promise<string | undefined>;
+}

package/vendor/core/creds/index.d.ts

@@ -0,0 +1,8 @@
+export { CredentialProxy, type CredentialProxyOptions, } from "./credential-proxy";
+export { type CredentialSource, credentialName } from "./credential-source";
+export { Credentials } from "./credentials";
+export { DotenvFile, type DotenvFileOptions } from "./dotenv-file";
+export { Environment, type EnvironmentOptions } from "./environment";
+export { MemorySecretStore } from "./memory-secret-store";
+export type { SecretStore } from "./secret-store";
+export { type ForProjectOptions, projectName, SystemSecretStore, } from "./system-secret-store";