@theholocron/cli 3.43.0 → 3.45.0

package/dist/capabilities/index.d.mts

@@ -12,7 +12,7 @@ import { ProviderApiError } from "@theholocron/http-client";
  * See `.notes/tech-architecture.spec.md` for the design narrative
  * (status: proposed, issue: #74).
  */
-type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "observability";
+type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "observability" | "wiki";
 type Cardinality = "single" | "many";
 declare const CARDINALITY: {
   readonly source: "single";
@@ -29,6 +29,7 @@ declare const CARDINALITY: {
   readonly notifications: "many";
   readonly analytics: "many";
   readonly observability: "many";
+  readonly wiki: "single";
 };
 /**
  * No capabilities are strictly required — repos without secrets (e.g. org
@@ -625,6 +626,41 @@ interface Observability extends ProviderIdentity {
     alreadyExists: boolean;
   }>;
 }
+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;
+}
+/**
+ * Engineering wiki provider.
+ *
+ * A swappable provider for publishing the `docs/decisions/` and
+ * `docs/engineering/` surfaces as a browsable, access-controlled site.
+ * Local-only providers (fern, mintlify) write config files; remote
+ * providers (github) make API calls.
+ */
+interface Wiki extends ProviderIdentity {
+  readonly key: "wiki";
+  /** Provision the wiki — write config files or call the provider API. */
+  provision(opts?: WikiProvisionOpts): Promise<string>;
+  /**
+   * DNS record needed for the custom domain, when one is configured.
+   * Returns null when no custom domain is set.
+   * Called by `setup` to provision the CNAME via the `dns` capability.
+   */
+  dnsRecord?(): WikiDnsRecord | null;
+}
 interface CapabilityImpls {
   source: Source;
   ci: Ci;
@@ -640,10 +676,11 @@ interface CapabilityImpls {
   notifications: Notifications;
   analytics: Analytics;
   observability: Observability;
+  wiki: Wiki;
 }
 type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
 /** Resolved runtime shape: single → one impl; many → array. */
 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, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, 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, isMulti };
+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, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, 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, isMulti };

package/dist/capabilities/index.mjs

@@ -14,7 +14,8 @@ const CARDINALITY = {
 	tooling: "many",
 	notifications: "many",
 	analytics: "many",
-	observability: "many"
+	observability: "many",
+	wiki: "single"
 };
 /**
 * No capabilities are strictly required — repos without secrets (e.g. org

package/dist/cli.mjs

@@ -137,7 +137,8 @@ const CARDINALITY = {
 	tooling: "many",
 	notifications: "many",
 	analytics: "many",
-	observability: "many"
+	observability: "many",
+	wiki: "single"
 };
 /**
 * No capabilities are strictly required — repos without secrets (e.g. org
@@ -3280,6 +3281,9 @@ var test_default$1 = "name: Test\n\non: # yamllint disable-line rule:truthy\n  p
 //#region src/commands/workflows/typecheck.yml
 var typecheck_default$1 = "name: Typecheck\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\nconcurrency:\n  group: typecheck-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n\njobs:\n  typecheck:\n    name: Typecheck\n    uses: theholocron/.github/.github/workflows/typecheck.yml@main\n    secrets: inherit\n";
 //#endregion
+//#region src/commands/workflows/wiki.yml
+var wiki_default$1 = "name: Wiki\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n\nconcurrency:\n  group: ${{ github.event_name == 'pull_request' && format('wiki-preview-{0}', github.event.pull_request.number) || 'wiki' }}\n  cancel-in-progress: ${{ github.event_name == 'pull_request' }}\n\npermissions:\n  contents: read\n\njobs:\n  publish:\n    name: Publish\n    if: ${{ github.event_name != 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/wiki.yml@main\n    secrets: inherit\n\n  preview:\n    name: Preview\n    if: ${{ github.event_name == 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/wiki.yml@main\n    with:\n      preview: true\n      preview-id: pr-${{ github.event.pull_request.number }}\n    secrets: inherit\n";
+//#endregion
 //#region src/commands/setup-workflows.ts
 /**
 * Header prepended to every auto-generated workflow thin caller.
@@ -3321,7 +3325,8 @@ const WORKFLOW_TEMPLATES = {
 	dependencies: dependencies_default$1,
 	bookkeeping: bookkeeping_default$1,
 	audit: audit_default$1,
-	deploy: deploy_default$1
+	deploy: deploy_default$1,
+	wiki: wiki_default$1
 };
 const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
 /**
@@ -4254,6 +4259,27 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 	}
+	if (loader.has("wiki")) {
+		const wiki = loader.get("wiki");
+		print(style.step("wiki"));
+		steps.push(await runStep("wiki", "provision wiki config", dryRun, async () => {
+			return await wiki.provision({ name: config.name });
+		}));
+		print(formatStep(steps[steps.length - 1]));
+		const wikiDns = wiki.dnsRecord?.();
+		if (wikiDns && loader.has("dns")) {
+			const dns = loader.get("dns");
+			steps.push(await runStep("dns", `upsertRecord ${wikiDns.cname}`, dryRun, async () => {
+				await dns.upsertRecord(wikiDns.zone, {
+					type: "CNAME",
+					name: wikiDns.cname,
+					content: wikiDns.target,
+					ttl: 1
+				});
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
 	if (loader.has("deployment")) {
 		const deploy = loader.get("deployment");
 		print(style.step("deployment"));
@@ -5358,6 +5384,9 @@ var test_default = "name: Test\n\non: # yamllint disable-line rule:truthy\n  wor
 //#region src/templates/workflows/typecheck.yml
 var typecheck_default = "name: Typecheck\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    secrets:\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  typecheck:\n    name: tsc --noEmit\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm typecheck\n        name: Type check\n\n\n  conclusion:\n    name: Conclusion\n    runs-on: ubuntu-latest\n    if: always()\n    needs: [typecheck]\n    steps:\n      - name: Check job statuses\n        run: |\n          if [[ \"$RESULTS\" == *\"failure\"* ]] || [[ \"$RESULTS\" == *\"cancelled\"* ]]; then\n            exit 1\n          fi\n        env:\n          RESULTS: ${{ join(needs.*.result, ',') }}\n";
 //#endregion
+//#region src/templates/workflows/wiki.yml
+var wiki_default = "name: Wiki\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      fern-version:\n        description: >\n          Fern CLI version to install. Pin this to avoid breaking changes when\n          Fern updates their config schema.\n        type: string\n        required: false\n        default: \"5.35.4\"\n      preview:\n        description: >\n          When true, publishes a preview instead of production.\n          Requires preview-id to be set.\n        type: boolean\n        required: false\n        default: false\n      preview-id:\n        description: >\n          Stable ID for the preview URL. The preview is accessible at\n          {fern-org}-preview-{id}.docs.buildwithfern.com. Use the PR number\n          (e.g. \"pr-123\") so the same URL is reused on every push to\n          the branch.\n        type: string\n        required: false\n        default: \"\"\n      fern-org:\n        description: >\n          Fern workspace org slug (e.g. \"holocron\"). When set, a GitHub\n          deployment is created after a successful preview so the URL appears\n          in the PR sidebar widget — the same pattern as Cloudflare Pages previews.\n        type: string\n        required: false\n        default: \"\"\n      base-path:\n        description: >\n          Basepath appended to the preview URL (e.g. \"holocron\" when using\n          multi-source routing with wiki.theholocron.dev/holocron).\n          Omit for single-instance Fern sites.\n        type: string\n        required: false\n        default: \"\"\n    secrets:\n      HOLOCRON_FERN_TOKEN:\n        required: false\n      FERN_TOKEN:\n        required: false\n\njobs:\n  publish:\n    name: ${{ inputs.preview && 'Preview' || 'Publish' }} to Fern\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    permissions:\n      contents: read\n      deployments: write\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - name: Install Fern CLI\n        run: npm install -g \"fern-api@$FERN_VERSION\"\n        env:\n          FERN_VERSION: ${{ inputs.fern-version }}\n\n      - name: Publish docs\n        if: ${{ !inputs.preview }}\n        run: fern generate --docs\n        env:\n          FERN_TOKEN: ${{ secrets.HOLOCRON_FERN_TOKEN || secrets.FERN_TOKEN }}\n\n      - name: Preview docs\n        if: ${{ inputs.preview && inputs.preview-id != '' }}\n        run: fern generate --docs --preview --id \"$PREVIEW_ID\"\n        env:\n          FERN_TOKEN: ${{ secrets.HOLOCRON_FERN_TOKEN || secrets.FERN_TOKEN }}\n          PREVIEW_ID: ${{ inputs.preview-id }}\n\n      - name: Report preview URL\n        if: ${{ inputs.preview && inputs.preview-id != '' && inputs.fern-org != '' }}\n        env:\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          FERN_ORG: ${{ inputs.fern-org }}\n          PREVIEW_ID: ${{ inputs.preview-id }}\n          BASE_PATH: ${{ inputs.base-path }}\n        run: |\n          PREVIEW_URL=\"https://${FERN_ORG}-preview-${PREVIEW_ID}.docs.buildwithfern.com${BASE_PATH:+/${BASE_PATH}}\"\n          PAYLOAD=$(printf '{\"ref\":\"%s\",\"environment\":\"fern (Preview)\",\"description\":\"Fern Docs\",\"production_environment\":false,\"auto_merge\":false,\"required_contexts\":[]}' \\\n            \"$GITHUB_HEAD_REF\")\n          DEPLOY_ID=$(echo \"$PAYLOAD\" | gh api \"repos/${GITHUB_REPOSITORY}/deployments\" \\\n            --method POST --input - | jq -r '.id')\n          gh api \"repos/${GITHUB_REPOSITORY}/deployments/${DEPLOY_ID}/statuses\" \\\n            --method POST --field state=success --field environment_url=\"$PREVIEW_URL\"\n";
+//#endregion
 //#region src/templates/index.ts
 /**
 * All reusable workflow and composite action content bundled as string
@@ -5392,7 +5421,8 @@ const REUSABLE_WORKFLOWS = {
 	"sync-github": sync_github_default,
 	sync: sync_default,
 	test: test_default,
-	typecheck: typecheck_default
+	typecheck: typecheck_default,
+	wiki: wiki_default
 };
 const WORKFLOW_TEMPLATE_PROPERTIES = { bookkeeping: JSON.stringify({
 	name: "Bookkeeping",