@theholocron/cli 5.0.0-alpha.6 → 5.0.0-alpha.61

package/dist/index.d.mts

@@ -1,7 +1,9 @@
-import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, NormalizedAuthUser, Notifications, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiDnsRecord, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti } from "./plugin/capabilities.mjs";
+import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, NormalizedAuthUser, Notifications, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti } from "./plugin/capabilities.mjs";
 import { AuthError, RequestOptions, ResolveTokenConfig as ResolveTokenConfig$1, ResolveTokenInput, RestClient, RestClientConfig, createRestClient } from "@theholocron/http-client";
 import { ConfigFileError } from "@theholocron/datapad";
+import { WorkspacePackage } from "@theholocron/astromech";
 import { LogLevel } from "@theholocron/observability/core";
+import { QualifiedConfig } from "@commitlint/types";
 //#region src/auth/auth-resolver.d.ts
 type ResolveTokenConfig = Omit<ResolveTokenConfig$1, "getKeyringToken">;
 /** Wraps `createResolveToken` from `@theholocron/http` and injects the
@@ -539,6 +541,98 @@ declare function resolvePluginPackage(provider: string): string;
 declare function resolveEntry(key: CapabilityKey, raw: RawProviderEntry): ResolvedProviderEntry;
 declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
 //#endregion
+//#region src/commands/setup/derived-properties.d.ts
+/**
+ * Derived custom-properties (#677). Unlike the existing 6 GitHub
+ * custom-properties fields (`lifecycle`, `open_source`, `runtime_environment`,
+ * `uses_external_packages`, `monorepo`, `branch_protection_level`) — which
+ * mirror what `holocron.config.ts` already states explicitly — these four are
+ * *derived*: signal that isn't an explicit config field today (framework
+ * choice, repo archetype, capability drift). See
+ * `.notes/tech-holocron-platform.spec.md` → "Custom-properties sync — field
+ * definitions (#677)" for the full design.
+ */
+type HolocronProfile = "library" | "cli" | "plugin" | "template" | "app" | "docs" | "platform";
+interface PackageJsonLike {
+  name?: string;
+  private?: boolean;
+  bin?: unknown;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+interface DeriveProfileInput {
+  rootPackageJson: PackageJsonLike | null;
+  repoName: string;
+  isMonorepo: boolean;
+  /** `packages/*` package.json contents, monorepo repos only — used to find the primary published artifact. */
+  workspacePackageJsons: PackageJsonLike[];
+}
+/**
+ * Repo archetype, in priority order:
+ * 1. `*-template` repo name → `template` (independent of package shape).
+ * 2. Monorepo whose primary published artifact is a CLI (some workspace
+ *    package has `bin`) → `platform` — matches `holocron` itself: the CLI is
+ *    the deliverable, the plugin packages are supporting infrastructure for
+ *    it, not separate products.
+ * 3. Monorepo with no CLI but at least one non-private workspace package →
+ *    `library` — matches `clients`/`configs`/`utils`/`themes`/
+ *    `observability`: a family of published packages, none of them a CLI.
+ *    Checked *before* falling into the root-package branch below, because
+ *    these repos' own root `package.json` is private and often carries
+ *    `@theholocron/astro-config` for a docs site built from the monorepo
+ *    root — without this check they'd wrongly resolve to `docs` off that
+ *    root-level signal alone, when the docs site is a secondary concern of
+ *    a library collection, not what the repo fundamentally is.
+ * 4. Single-package repo with `package.json#bin` → `cli`.
+ * 5. Docs-only site (astro/starlight present, root package private, no
+ *    publishable exports) → `docs`.
+ * 6. Private, non-publishable, non-docs → `app`.
+ * 7. Otherwise, a single publishable package → `library`.
+ */
+declare function deriveProfile(input: DeriveProfileInput): HolocronProfile;
+/**
+ * Detected build/framework tooling — the literal "does this repo need
+ * next/vite/tsdown" signal `holocron.config.ts` has no field for today
+ * (framework choice isn't a config concept, unlike `providers`/`tasks`).
+ * Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
+ * frameworks show up rather than trying to detect anything on npm.
+ */
+declare function deriveStack(pkg: PackageJsonLike | null): string[];
+/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
+declare function deriveCapabilities(providers: ResolvedProvidersConfig | undefined): string[];
+declare function deriveCompliance(capabilities: readonly string[]): "compliant" | "non-compliant";
+/**
+ * The Phase B refinement `deriveCompliance()`'s own doc comment names —
+ * *why* a repo is non-compliant, not just that it is. `[]` when compliant.
+ * Same `REQUIRED_BASELINE` `deriveCompliance()` checks against — one
+ * table, not two independently-maintained baselines.
+ */
+declare function missingCapabilities(capabilities: readonly string[]): string[];
+/**
+ * Reads each workspace package's actual `package.json` content (not just
+ * `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
+ * `platform` detection needs `bin`, which that helper doesn't carry).
+ * Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
+ * own soft-fail behavior.
+ */
+declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
+//#endregion
+//#region src/commit-lint/lint-message.d.ts
+interface CommitMessageViolation {
+  /** Rule name, e.g. `"subject-empty"`. */
+  rule: string;
+  /** commitlint's own message for the failure, e.g. `"subject may not be empty"`. */
+  message: string;
+}
+declare function lintCommitMessage(message: string, loaded: QualifiedConfig): Promise<CommitMessageViolation[]>;
+//#endregion
+//#region src/commit-lint/lint-commit-msg-file.d.ts
+interface LintCommitMsgFileResult {
+  valid: boolean;
+  violations: CommitMessageViolation[];
+}
+declare function lintCommitMsgFile(filePath: string, cwd?: string): Promise<LintCommitMsgFileResult>;
+//#endregion
 //#region src/config/compose.d.ts
 type TaskEntry = NonNullable<HolocronConfig["tasks"]>[number];
 /** A single composable capability fragment. */
@@ -617,4 +711,4 @@ interface LoadedConfig {
  */
 declare function loadConfig(cwd: string): Promise<LoadedConfig>;
 //#endregion
-export { Analytics, AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, Capability, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DocsConfig, DoctorConfig, EnsureResult, EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, FeatureResolverConfig, HolocronConfig, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, LoadedConfig, LogConfig, Logs, MultiEntry, NormalizedAuthUser, Notifications, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoConfig, RepoProperties, RepoProtection, RepoRef, RepoSettings, type RequestOptions, ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, StorybookDeployProject, TaskEntryConfig, TeamEntry, TeamPermission, TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiDnsRecord, WikiProvisionOpts, WikiProxyConfig, Workers, WorkflowWithConfig, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+export { Analytics, AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, Capability, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, CommitMessageViolation, ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, DeriveProfileInput, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, DocsConfig, DoctorConfig, EnsureResult, EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, FeatureResolverConfig, HolocronConfig, HolocronProfile, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, LintCommitMsgFileResult, LoadedConfig, LogConfig, Logs, MultiEntry, NormalizedAuthUser, Notifications, PackageJsonLike, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoConfig, RepoProperties, RepoProtection, RepoRef, RepoSettings, type RequestOptions, ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, StorybookDeployProject, TaskEntryConfig, TeamEntry, TeamPermission, TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, WorkflowWithConfig, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, lintCommitMessage, lintCommitMsgFile, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/dist/index.mjs

@@ -2,9 +2,11 @@ import { CARDINALITY, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificati
 import { AuthError, createResolveToken as createResolveToken$1, createRestClient } from "@theholocron/http-client";
 import { createEnvLookup } from "@theholocron/env-utils";
 import { Entry, findCredentials } from "@napi-rs/keyring";
-import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+import load from "@commitlint/load";
+import lint from "@commitlint/lint";
+import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { loadTasksConfig } from "@theholocron/astromech/config";
 import { ConfigFileError, ConfigFileError as ConfigFileError$1, loadConfigFile } from "@theholocron/datapad";
@@ -113,6 +115,170 @@ function createFeatureResolver(config) {
 	};
 }
 //#endregion
+//#region src/commands/setup/derived-properties.ts
+/**
+* Repo archetype, in priority order:
+* 1. `*-template` repo name → `template` (independent of package shape).
+* 2. Monorepo whose primary published artifact is a CLI (some workspace
+*    package has `bin`) → `platform` — matches `holocron` itself: the CLI is
+*    the deliverable, the plugin packages are supporting infrastructure for
+*    it, not separate products.
+* 3. Monorepo with no CLI but at least one non-private workspace package →
+*    `library` — matches `clients`/`configs`/`utils`/`themes`/
+*    `observability`: a family of published packages, none of them a CLI.
+*    Checked *before* falling into the root-package branch below, because
+*    these repos' own root `package.json` is private and often carries
+*    `@theholocron/astro-config` for a docs site built from the monorepo
+*    root — without this check they'd wrongly resolve to `docs` off that
+*    root-level signal alone, when the docs site is a secondary concern of
+*    a library collection, not what the repo fundamentally is.
+* 4. Single-package repo with `package.json#bin` → `cli`.
+* 5. Docs-only site (astro/starlight present, root package private, no
+*    publishable exports) → `docs`.
+* 6. Private, non-publishable, non-docs → `app`.
+* 7. Otherwise, a single publishable package → `library`.
+*/
+function deriveProfile(input) {
+	if (/-template$/.test(input.repoName)) return "template";
+	if (input.isMonorepo) {
+		if (input.workspacePackageJsons.some((pkg) => Boolean(pkg.bin))) return "platform";
+		if (input.workspacePackageJsons.some((pkg) => pkg.private !== true)) return "library";
+	}
+	const pkg = input.rootPackageJson;
+	if (pkg?.bin) return "cli";
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	const isDocsSite = Boolean(deps["@theholocron/astro-config"] || deps["astro"]);
+	if (pkg?.private && isDocsSite) return "docs";
+	if (pkg?.private) return "app";
+	return "library";
+}
+const KNOWN_STACK_DEPS = [
+	"next",
+	"vite",
+	"astro",
+	"tsdown",
+	"rollup",
+	"webpack",
+	"storybook",
+	"vitest",
+	"playwright",
+	"turbo"
+];
+/**
+* Detected build/framework tooling — the literal "does this repo need
+* next/vite/tsdown" signal `holocron.config.ts` has no field for today
+* (framework choice isn't a config concept, unlike `providers`/`tasks`).
+* Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
+* frameworks show up rather than trying to detect anything on npm.
+*/
+function deriveStack(pkg) {
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	return KNOWN_STACK_DEPS.filter((name) => name in deps);
+}
+/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
+function deriveCapabilities(providers) {
+	return Object.keys(providers ?? {}).sort();
+}
+/**
+* `source` + `ci` are the minimal baseline every repo `holocron setup`
+* touches wires — every `holocron.config.ts` in this org already satisfies
+* this, so `non-compliant` here means drift (a provider manually removed
+* after setup), not an unmet aspirational policy. Deliberately not a richer
+* per-profile policy yet (e.g. "a `library` must have `deployment`") — that's
+* a Phase B (GitHub App) refinement once it can post *why* on a check run.
+*/
+const REQUIRED_BASELINE = ["source", "ci"];
+function deriveCompliance(capabilities) {
+	return REQUIRED_BASELINE.every((key) => capabilities.includes(key)) ? "compliant" : "non-compliant";
+}
+/**
+* The Phase B refinement `deriveCompliance()`'s own doc comment names —
+* *why* a repo is non-compliant, not just that it is. `[]` when compliant.
+* Same `REQUIRED_BASELINE` `deriveCompliance()` checks against — one
+* table, not two independently-maintained baselines.
+*/
+function missingCapabilities(capabilities) {
+	return REQUIRED_BASELINE.filter((key) => !capabilities.includes(key));
+}
+/**
+* Reads each workspace package's actual `package.json` content (not just
+* `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
+* `platform` detection needs `bin`, which that helper doesn't carry).
+* Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
+* own soft-fail behavior.
+*/
+async function readWorkspacePackageJsons(repoRoot, workspacePackages) {
+	const results = [];
+	for (const { slug, dir = "packages" } of workspacePackages) try {
+		const raw = await readFile(join(repoRoot, dir, slug, "package.json"), "utf8");
+		results.push(JSON.parse(raw));
+	} catch {}
+	return results;
+}
+//#endregion
+//#region src/commit-lint/lint-message.ts
+/**
+* Lints one commit message string against an already-loaded commitlint
+* config. The genuinely environment-independent half of commit-message
+* linting (holocron#789) — *obtaining* a `QualifiedConfig` differs by
+* caller (Sentinel isolates itself from any ambient config since it runs
+* standalone, away from a real repo checkout; `lintCommitMsgFile` below
+* just lets cosmiconfig discover the invoking repo's own
+* `commitlint.config.*`, matching `commitlint --edit`'s own contract) —
+* but linting one message against a loaded config is identical either way.
+*
+* Real `@commitlint/lint` — the same programmatic API `@commitlint/cli`
+* itself uses internally — never a reimplementation of commitlint's rules.
+*/
+/** `parserPreset.parserOpts`, if the loaded config sets one — same lookup `@commitlint/cli`'s own `selectParserOpts()` does. */
+function selectParserOpts(parserPreset) {
+	return parserPreset?.parserOpts;
+}
+async function lintCommitMessage(message, loaded) {
+	const opts = {
+		/* istanbul ignore next -- see comment above */
+		parserOpts: selectParserOpts(loaded.parserPreset) ?? {},
+		plugins: loaded.plugins,
+		/* istanbul ignore next -- see comment above */
+		ignores: loaded.ignores ?? [],
+		defaultIgnores: loaded.defaultIgnores !== false
+	};
+	const outcome = await lint(message, loaded.rules, opts);
+	if (outcome.valid) return [];
+	return outcome.errors.map((error) => ({
+		rule: error.name,
+		message: error.message
+	}));
+}
+//#endregion
+//#region src/commit-lint/lint-commit-msg-file.ts
+/**
+* `holocron lint commit-msg <file>` — a real programmatic replacement for
+* shelling out to `commitlint --edit "$1"` from `.husky/commit-msg`
+* (holocron#789). Matches that CLI's own contract exactly: `file` is a
+* path to the commit message being written (the arg git's `commit-msg`
+* hook passes as `$1`), no `--config` override needed — `@commitlint/load`
+* runs from `cwd` with no seed, so cosmiconfig's own normal upward search
+* discovers the invoking repo's real `commitlint.config.*` file, exactly
+* as `commitlint --edit` (no `--config` flag) already does today. Unlike
+* Sentinel's `loadIsolatedConfig()`, no isolation is needed here — this
+* runs inside a real repo checkout with a real `node_modules`, not
+* standalone on a server.
+*/
+async function lintCommitMsgFile(filePath, cwd = process.cwd()) {
+	const violations = await lintCommitMessage(await readFile(filePath, "utf8"), await load({}, { cwd }));
+	return {
+		valid: violations.length === 0,
+		violations
+	};
+}
+//#endregion
 //#region src/config/config.ts
 var ConfigError = class extends Error {
 	name = "ConfigError";
@@ -389,4 +555,4 @@ function parseGitRemoteUrl(url) {
 	if (sshMatch) return sshMatch[1];
 }
 //#endregion
-export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, lintCommitMessage, lintCommitMsgFile, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/dist/plugin/capabilities.d.mts

@@ -136,10 +136,11 @@ interface Source extends ProviderIdentity {
    */
   syncLabels?(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
   /**
-   * Set org-level custom property values on the repo.
+   * Set org-level custom property values on the repo. `string[]` for
+   * `multi_select` properties, plain `string` for everything else.
    * Optional — providers that don't support custom properties omit this.
    */
-  syncProperties?(values: Record<string, string>): Promise<string>;
+  syncProperties?(values: Record<string, string | string[]>): Promise<string>;
   /**
    * Replace the repo's topic set with the supplied list.
    * Optional — providers that don't support topics omit this.
@@ -364,8 +365,32 @@ interface DeploymentRecord {
   status: "queued" | "building" | "ready" | "error" | "cancelled";
   createdAt?: string;
 }
+/** Config for `Deployment.deployFunction()` — source files, not a Git ref. */
+interface DeployFunctionConfig {
+  /**
+   * Files to deploy, keyed by path relative to the project root (e.g.
+   * `"api/webhook.js"`, `"package.json"`). Content is plain text — the
+   * provider handles any wire-format encoding.
+   */
+  files: Record<string, string>;
+  /**
+   * Named deployment target. Omit for a preview deployment — same
+   * semantics as `triggerDeployment`'s `target`.
+   */
+  target?: DeploymentTrigger;
+}
+interface DeployFunctionResult {
+  deploymentId: string;
+  url: string;
+}
 interface Deployment extends ProviderIdentity {
   readonly key: "deployment";
+  /**
+   * Custom domain declared in the deployment provider's configuration.
+   * `holocron setup` attaches it to the configured project and hands any
+   * returned verification record to the `dns` capability.
+   */
+  readonly domain?: string;
   listProjects(): Promise<DeploymentProject[]>;
   /** Create if missing, otherwise return existing. Idempotent. */
   ensureProject(input: {
@@ -389,6 +414,16 @@ interface Deployment extends ProviderIdentity {
     target?: DeploymentTrigger;
   }): Promise<DeploymentRecord>;
   getDeployment(deploymentId: string): Promise<DeploymentRecord>;
+  /**
+   * Deploy (or update) a project directly from source files, bypassing
+   * Git entirely — the non-git counterpart to `triggerDeployment`, for a
+   * consumer with no repo to link (a webhook receiver shipped as an npm
+   * package, for instance, rather than deployed from its own Git
+   * history). `projectId` may be a project name for providers that
+   * accept either. Optional — providers without a files-based deploy API
+   * omit this (e.g. Cloudflare Pages, git-source only today).
+   */
+  deployFunction?(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
   /**
    * List preview deployments for a specific branch alias (e.g. "repo-pr-42").
    * Optional — providers that don't support listing by branch omit this.
@@ -401,10 +436,18 @@ interface Deployment extends ProviderIdentity {
   deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
   /**
    * Add a custom domain (or wildcard) to the project. Idempotent — no-op
-   * when the domain is already present. Optional: providers without a custom
-   * domain API omit this (e.g. Vercel manages domains separately).
+   * when the domain is already present. Optional: providers without a
+   * custom domain API omit this.
+   *
+   * Returns the DNS record needed to finish verification — `null` when
+   * the domain is already verified, or when the provider's API doesn't
+   * surface DNS-challenge details at all (e.g. Cloudflare Pages, whose
+   * custom-domain flow doesn't expose the same per-request verification
+   * handshake Vercel's does). Callers hand a non-null result straight
+   * to `dns.upsertRecord(result.zone, result.record)` — the exact
+   * pattern `setup` already uses for `Wiki.dnsRecord()`.
    */
-  ensureCustomDomain?(projectId: string, hostname: string): Promise<void>;
+  ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
 }
 interface StorageBranch {
   id: string;
@@ -572,6 +615,17 @@ interface DnsRecord {
   priority?: number;
   proxied?: boolean;
 }
+/**
+ * A DNS record a capability wants created, plus which zone it belongs
+ * to — the shape `Wiki.dnsRecord()` and `Deployment.ensureCustomDomain()`
+ * both hand off to `Dns.upsertRecord()`. Not tied to either capability;
+ * any provider that needs "here's a record, go create it" returns this.
+ */
+interface DnsRecordRequest {
+  /** Zone apex passed as the first argument to `dns.upsertRecord`. */
+  zone: string;
+  record: DnsRecord;
+}
 interface Dns extends ProviderIdentity {
   readonly key: "dns";
   listRecords(domain: string): Promise<DnsRecord[]>;
@@ -650,18 +704,6 @@ interface WikiProvisionOpts {
   /** Project display name used in the wiki title (e.g. "Holocron"). */
   name?: string;
 }
-/**
- * DNS record that `setup` should create for a wiki custom domain.
- * Returned by `Wiki.dnsRecord()` when a custom domain is configured.
- */
-interface WikiDnsRecord {
-  /** Zone apex passed as the first argument to `dns.upsertRecord`. */
-  zone: string;
-  /** Full hostname for the CNAME (e.g. "wiki.theholocron.dev"). */
-  cname: string;
-  /** CNAME target (e.g. "holocron.docs.buildwithfern.com"). */
-  target: string;
-}
 /**
  * Reverse-proxy configuration returned by `Wiki.proxyConfig()`.
  * Used by `setup` to deploy a Worker that forwards traffic to the wiki
@@ -690,7 +732,7 @@ interface Wiki extends ProviderIdentity {
    * Returns null when no custom domain is set.
    * Called by `setup` to provision the CNAME via the `dns` capability.
    */
-  dnsRecord?(): WikiDnsRecord | null;
+  dnsRecord?(): DnsRecordRequest | null;
   /**
    * Reverse-proxy config when the wiki provider requires a Worker-level
    * proxy in addition to the CNAME. Returns null when no proxy is needed.
@@ -698,12 +740,34 @@ interface Wiki extends ProviderIdentity {
    */
   proxyConfig?(): WikiProxyConfig | null;
 }
+/** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
+interface DeployScriptConfig {
+  /** The full Worker script source — a single ES module (`export default { fetch(...) {...} }`). */
+  code: string;
+  /**
+   * Secret bindings — `env.<name>` in the deployed Worker. Values are
+   * write-only; the provider never echoes them back, here or anywhere else.
+   */
+  secrets?: Record<string, string>;
+  /**
+   * Route pattern(s) this Worker should serve (e.g.
+   * `"sentinel.theholocron.dev/*"`). Omit for a Worker reached only via
+   * its `*.workers.dev` URL.
+   */
+  routes?: string[];
+}
+interface DeployScriptResult {
+  /** The deployed script's name at the provider. */
+  scriptName: string;
+}
 /**
- * Edge Worker / reverse-proxy management capability.
+ * Edge Worker management capability.
  *
- * Deploys and manages Worker scripts that proxy traffic to a configured
- * target. Used by `setup` to wire wiki custom-domain proxies when the
- * wiki provider requires a Worker in addition to the CNAME.
+ * Deploys and manages Worker scripts. `upsertProxy` is the existing,
+ * narrower case `setup` uses to wire wiki custom-domain reverse-proxies;
+ * `deployScript` is the general case — any Worker, any code, its own
+ * secrets — for a consumer that isn't a reverse-proxy (a webhook
+ * receiver, for instance).
  */
 interface Workers extends ProviderIdentity {
   readonly key: "workers";
@@ -713,6 +777,8 @@ interface Workers extends ProviderIdentity {
    * `config.headers` on each request.
    */
   upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
+  /** Deploy (or update) an arbitrary Worker script, optionally with secrets and routes. */
+  deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
 }
 interface CapabilityImpls {
   source: Source;
@@ -738,4 +804,4 @@ type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
 type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
 declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
 //#endregion
-export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, NormalizedAuthUser, Notifications, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiDnsRecord, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };
+export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, NormalizedAuthUser, Notifications, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "5.0.0-alpha.6",
+  "version": "5.0.0-alpha.61",
   "description": "The Holocron CLI - a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "keywords": [
     "cli",
@@ -41,15 +41,18 @@
   ],
   "dependencies": {
     "@axiomhq/pino": "^2.0.0",
+    "@commitlint/lint": "^21.2.3",
+    "@commitlint/load": "^21.2.3",
+    "@commitlint/types": "^21.2.3",
     "@inquirer/prompts": "^8.5.2",
     "@inquirer/search": "^4.3.3",
     "@napi-rs/keyring": "^1.3.0",
     "@sentry/node": "^10.70.0",
     "@theholocron/components-doc": "^1.6.0",
     "@theholocron/env-utils": "^1.6.0",
-    "@theholocron/github-client": "^1.14.2",
-    "@theholocron/http-client": "^1.14.2",
-    "@theholocron/observability": "^0.3.0",
+    "@theholocron/github-client": "^1.29.0",
+    "@theholocron/http-client": "^1.25.0",
+    "@theholocron/observability": "^0.4.0",
     "@theholocron/registry-doc": "^1.12.0",
     "chalk": "^6.0.0",
     "ora": "^9.4.1",
@@ -57,13 +60,15 @@
     "pino-pretty": "^13.1.3",
     "posthog-node": "^5.51.6",
     "yargs": "^18.1.0",
-    "@theholocron/astromech": "5.0.0-alpha.6",
-    "@theholocron/datapad": "5.0.0-alpha.6"
+    "@theholocron/datapad": "5.0.0-alpha.61",
+    "@theholocron/astromech": "5.0.0-alpha.61"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/vitest-config": "^8.0.0",
+    "@commitlint/config-conventional": "^21.2.3",
+    "@theholocron/commitlint-config": "^8.4.5",
+    "@theholocron/eslint-config": "^8.4.5",
+    "@theholocron/tsconfig": "^8.4.5",
+    "@theholocron/vitest-config": "^8.4.5",
     "@types/node": "^26",
     "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^4.1.11",
@@ -75,7 +80,7 @@
     "tsx": "4.23.12",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/rollup-plugin-transform-template": "5.0.0-alpha.6"
+    "@theholocron/rollup-plugin-transform-template": "5.0.0-alpha.61"
   },
   "engines": {
     "node": ">=22.0.0"