heximon 0.0.1 → 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,405 @@
+import { CommandDef } from "citty";
+//#region src/prompter.d.ts
+/** Thrown when the operator cancels an interactive prompt (Ctrl-C). */
+declare class PromptCancelledError extends Error {
+  constructor();
+}
+/**
+ * The interactive-input surface, abstracted as a port so the CLI's {@link CredentialResolver} stays testable
+ * (a test injects a stub). It is a **CLI concept** — interactive prompting is how a human operator supplies a
+ * missing credential. The deploy library (`@heximon/deploy`) knows nothing of it: it consumes the resolved
+ * credential map this resolver produces. A non-interactive caller (a dashboard) has no prompter at all.
+ */
+interface Prompter {
+  /** Prompt for a secret value (input is masked). Rejects with {@link PromptCancelledError} on cancel. */
+  secret(message: string): Promise<string>;
+  /** Prompt for a non-secret value (input is visible). Rejects with {@link PromptCancelledError} on cancel. */
+  text(message: string): Promise<string>;
+}
+//#endregion
+//#region src/clack-prompter.d.ts
+/**
+ * The {@link Prompter} port backed by `@clack/prompts` — the one interactive surface the CLI exposes. A cancelled
+ * prompt (clack's sentinel symbol) is normalized to a thrown {@link PromptCancelledError} so the credential
+ * resolver handles one cancel failure mode.
+ */
+declare class ClackPrompter implements Prompter {
+  /** @throws PromptCancelledError when cancelled. */
+  secret(message: string): Promise<string>;
+  /** @throws PromptCancelledError when cancelled. */
+  text(message: string): Promise<string>;
+}
+//#endregion
+//#region src/cli-environment.d.ts
+/** Detects how the CLI is being run, so the deploy credential ladder knows whether interactive prompting is safe. */
+declare class CliEnvironment {
+  /**
+   * Whether this is an interactive session a prompt may block on: a real TTY on stdin AND not a CI runner. In CI
+   * (or a piped/non-TTY invocation) the deploy credential ladder must fail fast on a missing value rather than
+   * hang on a prompt no one can answer.
+   */
+  static isInteractive(): boolean;
+}
+//#endregion
+//#region src/project-scaffolder.d.ts
+/**
+ * A template fetch that failed — the giget ref could not be downloaded. Distinct from every local failure so a
+ * caller may retry another ref without also retrying (or cleaning up after) a validation or manifest error.
+ */
+declare class TemplateDownloadError extends Error {
+  /** The giget source string that could not be fetched. */
+  readonly gigetSource: string;
+  constructor(gigetSource: string, cause: unknown);
+}
+/** The template axes `heximon create` offers: the app shape and the request-body validator. */
+interface TemplateSelection {
+  /** The base template: the smallest real app, or the Drizzle/libsql CRUD app. */
+  readonly template: "minimal" | "database";
+  /** The validator variant; `"none"` selects the base template with hand-checked bodies. */
+  readonly validator: "zod" | "valibot" | "none";
+}
+/** Where a template comes from: the published starters repo (via giget) or a local directory. */
+interface TemplateSource {
+  /** A giget source string (e.g. `gh:heximon/starters/minimal#main`) — mutually exclusive with `localDirectory`. */
+  readonly gigetSource?: string;
+  /** A local starters directory to copy the template from (maintainer/dogfood path; no network). */
+  readonly localDirectory?: string;
+}
+/** The inputs {@link ProjectScaffolder.scaffold} materializes a project from. */
+interface ScaffoldRequest extends TemplateSelection {
+  /** The new project's directory name AND `package.json` name. */
+  readonly projectName: string;
+  /** The directory the project directory is created under. */
+  readonly parentDirectory: string;
+  /** Where the template content comes from. */
+  readonly source: TemplateSource;
+  /**
+   * The version stamped onto every `@heximon/*` dependency range (`^<version>`), normally the CLI's own
+   * lockstep version. `"workspace"` stamps `workspace:*` instead (in-monorepo dogfooding).
+   */
+  readonly heximonVersion: string;
+}
+/** A target directory {@link ProjectScaffolder.prepareTarget} accepted. */
+interface PreparedTarget {
+  /** The absolute project directory — always a direct child of the parent directory. */
+  readonly projectDirectory: string;
+  /**
+   * Whether this call created the directory. Only a directory this run created may be removed again; a
+   * pre-existing one belongs to the user, so a failed scaffold clears its own residue at most.
+   */
+  readonly createdDirectory: boolean;
+}
+/** What {@link ProjectScaffolder.scaffold} produced. */
+interface ScaffoldResult {
+  /** The absolute path of the created project directory. */
+  readonly projectDirectory: string;
+  /** The resolved template directory name (e.g. `"minimal-zod"`). */
+  readonly templateName: string;
+}
+/**
+ * Materializes a new Heximon project from a starters template: resolves the template directory name from
+ * the {@link TemplateSelection}, fetches (giget) or copies (local) it, then stamps the project name and
+ * the `@heximon/*` dependency ranges onto the fetched `package.json`. Pure filesystem work — prompting,
+ * git, and dependency installation live with the CLI command.
+ */
+declare class ProjectScaffolder {
+  /** A project/directory name: lowercase npm-safe segments (no scopes — the directory is the name). */
+  private static readonly projectNamePattern;
+  /**
+   * Resolve the concrete template directory name for a selection — the validator variant is a `-zod` /
+   * `-valibot` suffix; `"none"` selects the base directory.
+   *
+   * @param selection - The template + validator axes.
+   * @returns The starters directory name (e.g. `"database-valibot"`).
+   */
+  static templateNameOf(selection: TemplateSelection): string;
+  /**
+   * Validate a project name for use as both the directory and the `package.json` name.
+   *
+   * @param name - The candidate name.
+   * @returns `undefined` when valid, else a human-readable problem statement.
+   */
+  static validateProjectName(name: string): string | undefined;
+  /**
+   * Materialize the project: fetch/copy the template into `<parentDirectory>/<projectName>` and stamp the
+   * manifest. A target directory that already holds content is refused, never overwritten.
+   *
+   * @param request - What to scaffold, from where, and with which stamped versions.
+   * @returns The created project directory + the resolved template name.
+   */
+  scaffold(request: ScaffoldRequest): Promise<ScaffoldResult>;
+  /**
+   * Accept a target directory: the name must be valid, the resolved path must stay a direct child of the
+   * parent, and the directory must be absent or empty. A directory holding content is refused outright —
+   * `create` never overwrites.
+   *
+   * @param parentDirectory - The directory the project directory is created under.
+   * @param projectName - The candidate project (directory + package) name.
+   * @returns The accepted target, and whether this call created the directory.
+   */
+  static prepareTarget(parentDirectory: string, projectName: string): Promise<PreparedTarget>;
+  /**
+   * Discard what a failed scaffold left in a prepared target: the directory itself when this run created it,
+   * otherwise only the entries — a pre-existing directory was empty when accepted, so nothing else is ours.
+   */
+  static discardPreparedTarget(target: PreparedTarget): Promise<void>;
+  /** Fetch a giget template, tagging a fetch failure so a caller can tell it from a local error. */
+  private static fetchTemplate;
+  /**
+   * Rewrite the scaffolded `package.json`: the project name, and every `@heximon/*` range to the CLI's
+   * lockstep version (`^<version>`) or `workspace:*`.
+   */
+  private stampManifest;
+  /**
+   * Write the `.npmrc` scope line that routes `@heximon/*` installs to GitHub Packages — skipped when the
+   * template already ships its own `.npmrc` (never overwritten), and in workspace mode (`heximonVersion ===
+   * "workspace"`), where the `@heximon/*` ranges are workspace links and need no registry at all.
+   */
+  private static writeNpmrc;
+  /** Whether a filesystem path exists, of any kind. */
+  private static pathExists;
+  /** A directory's entries, or `undefined` when the directory does not exist. */
+  private static readEntries;
+}
+//#endregion
+//#region src/create-command.d.ts
+/** What {@link CreateDefaults.scaffoldFromStarters} materializes a project from. */
+interface StartersScaffoldRequest {
+  /** The template + validator axes. */
+  readonly selection: TemplateSelection;
+  /** The new project's directory (and package) name. */
+  readonly projectName: string;
+  /** The directory the project directory is created under. */
+  readonly parentDirectory: string;
+  /** The version stamped onto every `@heximon/*` range. */
+  readonly heximonVersion: string;
+  /** The starters directory name the giget source addresses. */
+  readonly templateName: string;
+}
+/** The `heximon create` verb: scaffold a new Heximon app from the starters templates. */
+declare const createCommand: CommandDef;
+/**
+ * The `create` command's defaults + environment glue: package-manager detection, the CLI's own lockstep
+ * version, the starters giget refs (version branch → main fallback), git init, and the install spawn.
+ */
+declare class CreateDefaults {
+  /** The default project (directory + package) name when none is given. */
+  static readonly projectName: string;
+  /** The GitHub repository the published templates are fetched from. */
+  static readonly startersRepository: string;
+  /**
+   * The CLI's own version — the framework version, since `heximon` releases in the lockstep group. It is
+   * what `@heximon/*` ranges are stamped to.
+   *
+   * @returns The version from this package's own manifest.
+   */
+  static cliVersion(): string;
+  /**
+   * Detect the invoking package manager from `npm_config_user_agent` (the create-vite trick).
+   *
+   * @param override - An explicit `--pm` value, which wins when given.
+   * @returns One of npm/pnpm/yarn/bun.
+   */
+  static resolvePackageManager(override: string | undefined): string;
+  /**
+   * Resolve the template + validator axes from flags, prompts, or defaults.
+   *
+   * @param template - The `--template` flag value, if any.
+   * @param validator - The `--validator` flag value, if any.
+   * @param options - Whether prompting is allowed.
+   * @returns The resolved selection, or `undefined` when the user cancelled a prompt.
+   */
+  static resolveSelection(template: string | undefined, validator: string | undefined, options: {
+    readonly interactive: boolean;
+  }): Promise<TemplateSelection | undefined>;
+  /**
+   * Scaffold from the published starters repository: try the CLI's `v<major.minor>` branch first (the
+   * templates matching this CLI's framework minor), falling back to `main`.
+   *
+   * The target is accepted before the first attempt, so a refusal (bad name, escaping path, existing
+   * content) never reaches the retry — the cleanup below discards only what this call itself created.
+   */
+  static scaffoldFromStarters(scaffolder: ProjectScaffolder, request: StartersScaffoldRequest): Promise<ScaffoldResult>;
+  /**
+   * `git init` the project directory, unless it already sits inside a work tree (or git is unavailable).
+   *
+   * @returns Whether a repository was initialized.
+   */
+  static initializeGit(projectDirectory: string): Promise<boolean>;
+  /** Run `<pm> install` in the project directory with inherited stdio (the user sees the real output). */
+  static runInstall(packageManager: string, projectDirectory: string): Promise<void>;
+  /** Run one starters attempt against a single giget ref. */
+  private static attemptScaffold;
+  /** Narrow a raw flag value to one of the allowed literals, or `undefined`. */
+  private static narrow;
+  /** Spawn a child process and resolve its exit code (non-zero-safe; spawn errors resolve to 1). */
+  private static run;
+}
+//#endregion
+//#region src/registry-access.d.ts
+/** The result of one spawned command, captured rather than inherited. */
+interface ProcessRunResult {
+  /** The process exit code (`null` becomes `1`). */
+  readonly exitCode: number;
+  /** Captured stdout. */
+  readonly stdout: string;
+  /** Captured stderr. */
+  readonly stderr: string;
+}
+/** Spawns a command and resolves its captured result. Injected so a test never spawns a real process. */
+type ProcessRunner = (command: string, commandArguments: readonly string[]) => Promise<ProcessRunResult>;
+/** The verdict {@link RegistryAccess.probe} classifies an `npm view` attempt into. */
+declare const RegistryAccessStatus: {
+  /** The probe package resolved — the registry is reachable and authorized. */
+  readonly Ok: "ok";
+  /** The registry rejected the request for lacking (or holding invalid) credentials. */
+  readonly Unauthorized: "unauthorized";
+  /** The registry could not be reached at all (DNS, network, timeout, an unrecognized failure). */
+  readonly Unreachable: "unreachable";
+  /** The registry was reached and authorized the request, but the probe package is not there. */
+  readonly NotFound: "not-found";
+};
+/** One of {@link RegistryAccessStatus}. */
+type RegistryAccessStatus = (typeof RegistryAccessStatus)[keyof typeof RegistryAccessStatus];
+/** What {@link RegistryAccess.probe} reports. */
+interface RegistryAccessReport {
+  /** The classified verdict. */
+  readonly status: RegistryAccessStatus;
+  /** The raw detail (stderr/stdout, or the spawn error message) behind the verdict, for diagnostics. */
+  readonly detail?: string;
+}
+/**
+ * Probes whether `@heximon/*` packages are readable from GitHub Packages, the private registry the
+ * framework publishes to (the `heximon` CLI itself stays on public npm). A scaffolded project needs a
+ * `.npmrc` scope line plus a token in the user's `~/.npmrc`; this probe reuses npm's own config
+ * resolution — the same files npm itself reads — so the verdict matches what an install would do.
+ */
+declare class RegistryAccess {
+  /** The private registry `@heximon/*` packages publish to. */
+  static readonly gitHubPackagesRegistry: string;
+  /** The package probed to decide reachability — small, always published, always current. */
+  static readonly probePackage: string;
+  /** The scope line a scaffolded project's `.npmrc` carries, routing `@heximon/*` to GitHub Packages. */
+  static readonly npmrcScopeLine: string;
+  private readonly run;
+  /**
+   * @param run - The process runner to probe with. Defaults to spawning `npm` for real; a test injects a
+   * stub so the probe never touches the network.
+   */
+  constructor(run?: ProcessRunner);
+  /**
+   * Runs `npm view @heximon/runtime version` against GitHub Packages and classifies the result.
+   *
+   * @returns The classified verdict, with the raw output kept as `detail` for diagnostics.
+   */
+  probe(): Promise<RegistryAccessReport>;
+  /**
+   * The fix instructions printed when {@link probe} does not report {@link RegistryAccessStatus.Ok}.
+   *
+   * @param status - The non-Ok verdict, when known — shapes the wording between an auth fix and a network hint.
+   */
+  static fixInstructions(status?: RegistryAccessStatus): string;
+  /** The default {@link ProcessRunner}: spawns `npm` for real, capturing stdout/stderr. */
+  private static spawnProcess;
+}
+//#endregion
+//#region src/skill-installer.d.ts
+/** One installed skill: its name and how many files were written. */
+interface InstalledSkill {
+  readonly name: string;
+  readonly fileCount: number;
+}
+/**
+ * Installs the published Heximon agent skill into a scaffolded project from the docs site's RFC 8615
+ * well-known endpoint — `/.well-known/skills/index.json` plus `/.well-known/skills/<name>/<file>`, the
+ * same layout `npx skills add https://heximon.dev` consumes (Docus serves the docs repo's `skills/`
+ * directory there natively). Best-effort by contract: the caller treats a throw as a skippable step with
+ * a printed hint, never a scaffold failure.
+ */
+declare class SkillInstaller {
+  private readonly sourceUrl;
+  /** The published docs site serving the skill. */
+  static readonly defaultSourceUrl = "https://heximon.dev";
+  /** Where skills land inside the project — the universal agent layout; `.claude/skills` symlinks here. */
+  private static readonly targetDirectory;
+  /** Per-agent skills directories, each created as a relative symlink onto {@link targetDirectory}. */
+  private static readonly agentSymlinks;
+  /** Per-request timeout — scaffolding must never hang on an unreachable docs deploy. */
+  private static readonly fetchTimeoutMs;
+  constructor(sourceUrl?: string);
+  /**
+   * Install every skill the source publishes into `projectDirectory`.
+   *
+   * @returns The installed skills, in index order.
+   * @throws {Error} When the index is unreachable/malformed or any listed file fails to download.
+   */
+  install(projectDirectory: string): Promise<readonly InstalledSkill[]>;
+  /**
+   * Point each per-agent skills directory (`.claude/skills`) at the universal `.agents/skills` copy via a
+   * relative symlink, so every agent convention reads the one install. Best-effort: an existing entry is
+   * left untouched, and a filesystem that cannot symlink (e.g. Windows without developer mode) is not an
+   * install failure — the universal copy stands on its own.
+   */
+  private static linkAgentDirectories;
+  /** Fetch and validate the discovery index, keeping only well-shaped entries with safe names. */
+  private static fetchIndex;
+  /** A relative file path with no traversal, absolute prefix, or backslash trickery. */
+  private static isSafeRelativePath;
+  private static fetchJson;
+  private static fetchText;
+}
+//#endregion
+//#region src/skill-sources.d.ts
+/**
+ * The project's recorded agent-skill sources, persisted as `heximon.skills` in its `package.json`.
+ *
+ * The manifest rather than the config sidecar, for one reason: `heximon create` records the default source
+ * before an app exists to compile, and a tool reads the list without evaluating any TypeScript. Every entry
+ * is a base URL {@link SkillInstaller} can install from — the same value `npx skills add <url>` takes.
+ */
+declare abstract class SkillSources {
+  /** The `package.json` member holding the framework's own manifest block. */
+  private static readonly manifestKey;
+  /** The member of that block holding the source list. */
+  private static readonly listKey;
+  /**
+   * The sources recorded for a project, in the order they were added.
+   *
+   * @param projectDirectory - The project root holding `package.json`.
+   * @returns The recorded base URLs; empty when the manifest records none (or has no readable list).
+   * @throws {Error} When `package.json` is missing or is not readable JSON — a project whose manifest cannot
+   *   be read is not one to silently report as having no skills.
+   */
+  static read(projectDirectory: string): Promise<readonly string[]>;
+  /**
+   * Record one source, leaving every other manifest member untouched.
+   *
+   * @param projectDirectory - The project root holding `package.json`.
+   * @param sourceUrl - The base URL to record, normalized by {@link normalize} first.
+   * @returns `true` when the source was added, `false` when it was already recorded — so recording twice is
+   *   a no-op the caller can report as such rather than a duplicated entry.
+   */
+  static record(projectDirectory: string, sourceUrl: string): Promise<boolean>;
+  /**
+   * The canonical form of a source URL: trailing slashes removed, so `https://heximon.dev/` and
+   * `https://heximon.dev` are one recorded entry rather than two installs of the same site.
+   */
+  static normalize(sourceUrl: string): string;
+  /** Whether a string is an absolute `http`/`https` URL — the only form the installer can fetch from. */
+  static isInstallable(sourceUrl: string): boolean;
+  /** The project manifest as a mutable record. */
+  private static readManifest;
+}
+//#endregion
+//#region src/skills-command.d.ts
+/**
+ * The `heximon skills` command — install the published agent skills into a project and keep the list of
+ * sources in `package.json` (`heximon.skills`), so a second machine or a fresh clone reproduces the same
+ * install with one verb instead of a remembered URL.
+ *
+ * `heximon create` already installs the default source and records it, so an existing project's first use of
+ * this command is usually `sync` after a clone, or `add` for a second, private skill site.
+ */
+declare const skillsCommand: CommandDef;
+//#endregion
+export { ClackPrompter, CliEnvironment, CreateDefaults, type InstalledSkill, type PreparedTarget, type ProcessRunResult, type ProcessRunner, ProjectScaffolder, PromptCancelledError, type Prompter, RegistryAccess, type RegistryAccessReport, RegistryAccessStatus, type ScaffoldRequest, type ScaffoldResult, SkillInstaller, SkillSources, type StartersScaffoldRequest, TemplateDownloadError, type TemplateSelection, type TemplateSource, createCommand, skillsCommand };

package/dist/index.mjs

@@ -1,6 +1,2 @@
-// heximon — placeholder package.
-// This name is reserved for future development. There is no functionality yet.
-
-console.warn("heximon is a placeholder package and has no functionality yet.");
-
-export default {};
+import { a as SkillInstaller, c as RegistryAccess, d as ClackPrompter, f as PromptCancelledError, i as SkillSources, l as RegistryAccessStatus, n as CreateDefaults, o as ProjectScaffolder, r as createCommand, s as TemplateDownloadError, t as skillsCommand, u as CliEnvironment } from "./skills-command-W72zUEYD.mjs";
+export { ClackPrompter, CliEnvironment, CreateDefaults, ProjectScaffolder, PromptCancelledError, RegistryAccess, RegistryAccessStatus, SkillInstaller, SkillSources, TemplateDownloadError, createCommand, skillsCommand };