Holocron

Holocron

A pluggable, capability-based CLI for spinning up and operating software projects — your own infrastructure-as-tool.

Installation

This repository is a workspace root — it is not published. See the workspace packages for the tools it ships.

1. Install the CLI + the source plugin and a vault plugin

pnpm add -g @theholocron/cli
pnpm add -D @theholocron/holocron-plugin-github

# Vault — pick one: 1password, doppler, or infisical
pnpm add -D @theholocron/holocron-plugin-doppler
# or: pnpm add -D @theholocron/holocron-plugin-1password
# or: pnpm add -D @theholocron/holocron-plugin-infisical

2. Drop a holocron.config.ts at your repo root

Create the config (e.g. holocron.config.{ts | js | json}

import { defineConfig } from "@theholocron/cli";
import { nodePreset } from "@theholocron/cli/presets";

const { repo, workflows, providers } = nodePreset();
export default defineConfig({
	description: "Custom app that does custom things.",
	repo: {
		teams: [{ slug: "gatekeepers", permission: "maintain" }],
		topics: ["automation", "cli", "developer-tools", "holocron", "nodejs", "typescript"],
		...repo,
	},
	workflows,
	providers: {
		...providers,
		vault: ["doppler", { project: "holocron", config: "dev" }],
		secrets: "github",
		environments: "github",
	},
	agent: "claude",
	skills: ["git-safety", "pr-workflow", "commit-standards", "security-review", "holocron-skill-plugin", "turborepo"],
});

3. Store fine-grained PATs in the OS keyring (once per machine)

See docs/tokens.md for the full list of feature tokens and required scopes.

holocron auth set github.read    ghp_...  # clone + CI
holocron auth set github.admin   ghp_...  # setup + secrets + environments

4. Verify the wiring

holocron doctor

Every additional capability (ci, secrets, deployment, storage, auth, …) is one plugin install + one line of config away. The rest of this README is the full picture.

The idea

Many projects share the same setup work: pick a hosting provider, a database, an auth provider, a secret vault, a CI hosting provider. Wire all the secrets, the workflows, the deploys, the issue tracker. Holocron makes that work declarative, swappable, and re-runnable.

// holocron.config.json
{
  "name": "my-app",

  "providers": {
    // Code + CI
    "source": "github",
    "ci": "github",
    "secrets": "github",
    "environments": "github",
    "issues": "github",

    // Hosting + data
    "deployment": ["vercel", { "team": "my-team" }],
    "storage": ["neon", { "kind": "postgres" }],
    "auth": "clerk",
    "dns": "cloudflare",

    // Source of truth for secrets (required)
    "vault": ["1password", { "vault": "my-app" }],

    // Error + log providers (single; also env-var-activated)
    "errors": "sentry",
    "logs": "axiom",

    // Multi-provider
    "tooling": ["postman", "storybook"],
    "notifications": ["slack", "discord"],
    "analytics": ["google"],
  },
}

Then:

holocron repo setup      # apply the whole config, top to bottom
holocron repo sync       # sync README, labels, topics, keywords from config
holocron sync readme     # readme marker blocks only
holocron doctor          # check everything's wired right
holocron secrets sync    # vault → secrets + deployment env vars + .env
holocron deploy          # ship to your `deployment` provider

How it works

• Capabilities are the contracts (14 of them — see the architecture spec).
• Plugins are npm packages named holocron-plugin-<provider> (or @theholocron/holocron-plugin-<provider> for the built-in set). Each plugin exports the capabilities it implements — a single provider can cover several (GitHub does source + CI + issues + secrets + environments).
• Config is ESLint-style: short form "vercel" for defaults, tuple form ["vercel", { team: "my-team" }] for options, multi-list ["slack", "discord"] for capabilities that allow several providers active at once.

The vault

Every project has secrets somewhere. They don't go in the repo, they don't go in the config — they go in the vault, which is the only required capability. Everything else that needs secrets (CI, runtime env vars, local .env) syncs FROM the vault:

vault (1Password)
  ├─ secrets       (GitHub Actions)
  ├─ deployment    (Vercel env vars)
  └─ local.env    (for dev)

Repo layout (v2)

cli/                                 — core infrastructure                            (the CLI and its runtime)
  astromech/                         — @theholocron/astromech                         (task runner — holocron run / ci)
  datapad/                           — @theholocron/datapad                           (config-file loader — <name>.config.*)
  cli/                               — @theholocron/cli                               (binary + capability runtime)
apps/                                — deployable applications (not published to npm)
  sentinel/                          — @theholocron/sentinel                          (minimal GitHub App — scaffolding only)
observability/                        — @theholocron/observability                     (logging, error tracking and analytics behind one interface)
skills/                               — @theholocron/skills                     (shared agent skill registry)
plugins/                             — vendor capability providers                    (one package per provider)
  holocron-plugin-github/            — @theholocron/holocron-plugin-github            (source, ci, secrets, environments, issues)
  holocron-plugin-vercel/            — @theholocron/holocron-plugin-vercel            (deployment)
  holocron-plugin-netlify/           — @theholocron/holocron-plugin-netlify           (deployment)
  holocron-plugin-neon/              — @theholocron/holocron-plugin-neon              (storage)
  holocron-plugin-clerk/             — @theholocron/holocron-plugin-clerk             (auth)
  holocron-plugin-cloudflare/        — @theholocron/holocron-plugin-cloudflare        (dns)
  holocron-plugin-1password/         — @theholocron/holocron-plugin-1password         (vault — CLI shell-out)
  holocron-plugin-doppler/           — @theholocron/holocron-plugin-doppler           (vault — REST)
  holocron-plugin-infisical/         — @theholocron/holocron-plugin-infisical         (vault — REST)
  holocron-plugin-discord/           — @theholocron/holocron-plugin-discord           (notifications)
  holocron-plugin-fern/              — @theholocron/holocron-plugin-fern              (wiki)
  holocron-plugin-axiom/             — @theholocron/holocron-plugin-axiom             (logs — REST)
  holocron-plugin-slack/             — @theholocron/holocron-plugin-slack             (notifications)
  holocron-plugin-postman/           — @theholocron/holocron-plugin-postman           (tooling)
  holocron-plugin-posthog/           — @theholocron/holocron-plugin-posthog           (analytics)
  holocron-plugin-sentry/            — @theholocron/holocron-plugin-sentry            (errors)
  holocron-plugin-checkly/           — @theholocron/holocron-plugin-checkly           (monitoring)
holocron.config.ts                   — this repo's own holocron config                (self-hosted)
.notes/                              — in-progress design specs                       (settled ones move to docs/wiki/specifications/)
.claude/skills/holocron-plugin.md    — scaffolding skill for new plugins

Self-hosting

This repo carries its own holocron.config.ts so holocron commands work inside it, and publishes its own packages via npm Trusted Publishing (OIDC — no stored NPM_TOKEN). Setup + new-package bootstrap live in docs/self-hosting.md.

License

MIT. See LICENSE.