arkgate 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1249 -0
- package/LICENSE +21 -0
- package/README.md +218 -0
- package/SECURITY.md +39 -0
- package/bin/ark-check.mjs +5204 -0
- package/bin/ark-mcp.mjs +898 -0
- package/bin/ark-shared.mjs +1520 -0
- package/bin/ark.mjs +491 -0
- package/dist/eslint/index.cjs +222 -0
- package/dist/eslint/index.cjs.map +1 -0
- package/dist/eslint/index.d.cts +42 -0
- package/dist/eslint/index.d.ts +40 -0
- package/dist/eslint/index.js +193 -0
- package/dist/eslint/index.js.map +1 -0
- package/dist/index.cjs +3080 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +577 -0
- package/dist/index.d.ts +577 -0
- package/dist/index.js +2998 -0
- package/dist/index.js.map +1 -0
- package/dist/nestjs/index.cjs +2332 -0
- package/dist/nestjs/index.cjs.map +1 -0
- package/dist/nestjs/index.d.cts +22 -0
- package/dist/nestjs/index.d.ts +22 -0
- package/dist/nestjs/index.js +2308 -0
- package/dist/nestjs/index.js.map +1 -0
- package/dist/types-DpdVN7Lm.d.cts +1023 -0
- package/dist/types-DpdVN7Lm.d.ts +1023 -0
- package/docs/agent-guide.md +490 -0
- package/docs/ai-gates.md +337 -0
- package/docs/ark-check-example.json +87 -0
- package/docs/assets/ark-write-gate.svg +28 -0
- package/docs/brownfield-adoption.md +87 -0
- package/docs/demos/01-write-gate-self-correction.md +74 -0
- package/docs/demos/02-brownfield-baseline-adoption.md +71 -0
- package/docs/demos/03-copilot-autopilot.md +83 -0
- package/docs/enthusiast/README.md +62 -0
- package/docs/enthusiast/explanation-application-shape.md +29 -0
- package/docs/enthusiast/how-to-agent-gates.md +36 -0
- package/docs/enthusiast/how-to-gallery-starter.md +27 -0
- package/docs/enthusiast/how-to-pick-shape.md +45 -0
- package/docs/enthusiast/how-to-policy-pack.md +37 -0
- package/docs/enthusiast/reference-archetypes.md +36 -0
- package/docs/enthusiast/reference-commands.md +50 -0
- package/docs/enthusiast/tutorial-first-project.md +86 -0
- package/docs/production-hardening.md +59 -0
- package/package.json +125 -0
- package/server.json +39 -0
- package/templates/architecture-playbook.json +339 -0
- package/templates/policy-packs/enthusiast-feature-sliced.json +20 -0
- package/templates/policy-packs/enthusiast-hexagonal.json +18 -0
- package/templates/policy-packs/enthusiast-layered.json +18 -0
- package/templates/policy-packs/enthusiast-monorepo.json +18 -0
- package/templates/skills/ark-adopt.md +103 -0
- package/templates/skills/ark-architect.md +90 -0
- package/templates/skills/ark-autopilot.md +95 -0
- package/templates/skills/ark-contract.md +98 -0
- package/templates/skills/ark-coverage.md +96 -0
- package/templates/skills/ark-explain.md +78 -0
- package/templates/skills/ark-fix.md +96 -0
- package/templates/skills/ark-loop.md +69 -0
- package/templates/skills/ark-place.md +68 -0
- package/templates/skills/ark-runtime.md +62 -0
- package/templates/skills/ark-upgrade.md +109 -0
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Demo: the co-pilot autopilot, end to end
|
|
2
|
+
|
|
3
|
+
Take a project from "no guardrails" to "governed, cleaned up, and enforced" — the way a
|
|
4
|
+
non-developer would, driving an agent. This is the Phase F→G→H→I flow (plan · guided setup ·
|
|
5
|
+
loop · autopilot) in one sitting.
|
|
6
|
+
|
|
7
|
+
## In one line
|
|
8
|
+
|
|
9
|
+
`npx ark start` sets it up and shows a plan; **`/ark-autopilot`** (in your agent) carries the
|
|
10
|
+
plan out — applying the safe fixes and proposing the rest, always validated by `ark-check`.
|
|
11
|
+
|
|
12
|
+
## Prerequisites
|
|
13
|
+
|
|
14
|
+
- Ark built or installed from this repository
|
|
15
|
+
- An agent CLI (Claude, Cursor, Codex, Grok, …) for the `/ark-autopilot` and `/ark-loop` steps
|
|
16
|
+
|
|
17
|
+
## Steps
|
|
18
|
+
|
|
19
|
+
### 1. Guided setup (no architecture knowledge needed)
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
TMP=$(mktemp -d); cd "$TMP"
|
|
23
|
+
git init -q # the loop works in a discardable worktree
|
|
24
|
+
npm init -y >/dev/null
|
|
25
|
+
npx ark start --yes
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Ark describes the project's shape in plain language, writes `ark.config.json` + agent/CI gates,
|
|
29
|
+
and prints the **plan** — how many fixes are _safe to auto-apply_ vs _need your decision_ —
|
|
30
|
+
plus which **operating mode** applies: **suggest**, **adapt**, or **enforce**.
|
|
31
|
+
|
|
32
|
+
On Nest/Next/express/library projects, init also merges framework filename conventions into
|
|
33
|
+
the layer globs so day-one **governed%** is real (not a false-green empty contract).
|
|
34
|
+
|
|
35
|
+
### 2. See the plan yourself (optional)
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npx ark-check --plan # human view (includes Governed: N%)
|
|
39
|
+
npx ark-check --plan --json # { ok, plan: { goal, counts, steps } }
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence` and a
|
|
43
|
+
plain-language `rationale`. `goal.met` is true only when there are no active violations **and**
|
|
44
|
+
governed coverage is meaningful — so a clean plan that checks almost nothing is not "done."
|
|
45
|
+
|
|
46
|
+
### 3. Carry the plan out — the autopilot
|
|
47
|
+
|
|
48
|
+
In your agent, run:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
/ark-autopilot
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
It runs the whole flow (newbie tier): confirms the plan, hands off to `/ark-loop` to apply the
|
|
55
|
+
`mechanical-safe` steps one at a time — **validating each with `ark-check` and rolling back any
|
|
56
|
+
regression** — proposes each `judgment` step for a yes/no, loops until `goal.met`, and reports
|
|
57
|
+
what was auto-applied vs proposed vs deferred. Nothing lands until you review the diff.
|
|
58
|
+
|
|
59
|
+
Expert entry: skip the autopilot and use the pieces — `ark init` / `/ark-contract` to shape the
|
|
60
|
+
contract, `ark-check --plan` for the work, `/ark-fix` for targeted fixes, `ark-check
|
|
61
|
+
--strict-config` as the gate. Same contract, same gates; same suggest/adapt/enforce modes.
|
|
62
|
+
|
|
63
|
+
### 4. It stays clean
|
|
64
|
+
|
|
65
|
+
The gates installed in step 1 keep enforcing the architecture from now on — in CI, and at write
|
|
66
|
+
time if the MCP hook is wired. Verify:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npx ark-check --root . --config ark.config.json --strict-config
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## What this proves
|
|
73
|
+
|
|
74
|
+
- **plan + goal** (Phase F): `ark-check --plan` classifies the work and defines "done" (with
|
|
75
|
+
governed% honesty).
|
|
76
|
+
- **guided setup** (Phase G): `ark start` — no preset or skill name required; modes
|
|
77
|
+
suggest / adapt / enforce.
|
|
78
|
+
- **loop** (Phase H): `/ark-loop` — safe, reversible, validated apply.
|
|
79
|
+
- **autopilot** (Phase I): `/ark-autopilot` — the whole thing, with newbie/expert entry styles.
|
|
80
|
+
- **field honesty** (2.0): framework overlays + no false-green at 0% governed.
|
|
81
|
+
|
|
82
|
+
The classifier's precision (only provably-safe changes are ever `mechanical-safe`) is guarded
|
|
83
|
+
by the classifier corpus test in `tests/unit/static-check/arkCheck.test.ts`.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Ark — Architecture Co-pilot (enthusiast track)
|
|
2
|
+
|
|
3
|
+
Plain-language onboarding for builders who use AI agents but are not professional
|
|
4
|
+
developers. This track follows [Diátaxis](https://diataxis.fr/): tutorial, how-to,
|
|
5
|
+
reference, and explanation.
|
|
6
|
+
|
|
7
|
+
## How Ark talks to you (2.0)
|
|
8
|
+
|
|
9
|
+
**Entry style** — who is driving: *newbie* (`ark start` / `/ark-autopilot`) vs *expert* (individual commands).
|
|
10
|
+
|
|
11
|
+
**Operating mode** — what Ark is doing right now (one contract underneath):
|
|
12
|
+
|
|
13
|
+
| Mode | Meaning |
|
|
14
|
+
|------|---------|
|
|
15
|
+
| **Suggest** | Propose an application shape and install a starter contract. |
|
|
16
|
+
| **Adapt** | Match the contract to your real layout / raise governed coverage. |
|
|
17
|
+
| **Enforce** | The contract actually governs your code; gates hold the line. |
|
|
18
|
+
|
|
19
|
+
`ark start` and `ark-check --plan` will not claim "everything is guarded" while governed coverage is near zero. On Nest/Next/express starters, init also merges **framework filename conventions** into the layer globs so day-one coverage is real.
|
|
20
|
+
|
|
21
|
+
## Start here
|
|
22
|
+
|
|
23
|
+
| Type | Document | You will… |
|
|
24
|
+
|------|----------|-----------|
|
|
25
|
+
| **Tutorial** | [First project in 15 minutes](tutorial-first-project.md) | Walk the full path once: recommend → init → verify |
|
|
26
|
+
| **How-to** | [Pick your application shape](how-to-pick-shape.md) | Run `--recommend` / `ark_recommend` and read the plan |
|
|
27
|
+
| **How-to** | [Use a gallery starter](how-to-gallery-starter.md) | Copy a phase-1 scaffold that matches your archetype |
|
|
28
|
+
| **How-to** | [Apply an enthusiast policy pack](how-to-policy-pack.md) | Write `ark.config.json` from a named preset |
|
|
29
|
+
| **How-to** | [Install agent gates](how-to-agent-gates.md) | Wire the write gate and `/ark-*` skills |
|
|
30
|
+
| **Reference** | [Archetypes and presets](reference-archetypes.md) | Look up playbook ids, presets, and phase-1 layers |
|
|
31
|
+
| **Reference** | [Commands and artifacts](reference-commands.md) | `--recommend`, `--write-plan`, `ark-adoption-plan.json`, fix-class JSON |
|
|
32
|
+
| **Explanation** | [Why application shape matters](explanation-application-shape.md) | Understand shapes vs frameworks and progressive phases |
|
|
33
|
+
|
|
34
|
+
## Public demos (Phase D)
|
|
35
|
+
|
|
36
|
+
Reproducible scripts — no video required:
|
|
37
|
+
|
|
38
|
+
- [Write-gate self-correction](../demos/01-write-gate-self-correction.md)
|
|
39
|
+
- [Brownfield baseline adoption](../demos/02-brownfield-baseline-adoption.md)
|
|
40
|
+
## Gallery starters
|
|
41
|
+
|
|
42
|
+
| Archetype | Directory |
|
|
43
|
+
|-----------|-----------|
|
|
44
|
+
| `crud-product` | [examples/crud-product-starter](../../examples/crud-product-starter/) |
|
|
45
|
+
| `api-backend` | [examples/api-backend-starter](../../examples/api-backend-starter/) |
|
|
46
|
+
| `worker-pipeline` | [examples/worker-pipeline-starter](../../examples/worker-pipeline-starter/) |
|
|
47
|
+
| `multi-app-workspace` | [examples/multi-app-workspace-starter](../../examples/multi-app-workspace-starter/) |
|
|
48
|
+
|
|
49
|
+
Deep teaching example (runnable API + break exercises): [hexagonal-order-api](../../examples/hexagonal-order-api/).
|
|
50
|
+
|
|
51
|
+
## Brownfield vs greenfield
|
|
52
|
+
|
|
53
|
+
| Situation | Use |
|
|
54
|
+
|-----------|-----|
|
|
55
|
+
| New or empty repo | `/ark-architect`, `ark-check --recommend`, gallery starters |
|
|
56
|
+
| Existing messy codebase | `/ark-adopt`, [brownfield playbook](../brownfield-adoption.md) |
|
|
57
|
+
|
|
58
|
+
## Related
|
|
59
|
+
|
|
60
|
+
- [Agent integration guide](../agent-guide.md)
|
|
61
|
+
- [Public demos](../demos/)
|
|
62
|
+
- [Examples index](../../examples/README.md)
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Explanation: why application shape matters
|
|
2
|
+
|
|
3
|
+
Ark separates **what you are building** from **which framework you installed**.
|
|
4
|
+
|
|
5
|
+
A “todo app with a database” is an application shape (`crud-product`). Next.js, Vite, or
|
|
6
|
+
Prisma are detection signals that may raise confidence — they do not define the archetype
|
|
7
|
+
label shown to you or your agent.
|
|
8
|
+
|
|
9
|
+
## Progressive phases
|
|
10
|
+
|
|
11
|
+
Phase 1 is deliberately small (typically 2–4 layers). Phase 2 and 3 unlock when you
|
|
12
|
+
describe new capabilities (payments, email, background jobs, sagas). This keeps enthusiasts
|
|
13
|
+
from drowning in the full 11-layer profile on day one.
|
|
14
|
+
|
|
15
|
+
## Honesty over green
|
|
16
|
+
|
|
17
|
+
`ark-check --strict-config` and `--coverage` report how much of the tree is actually
|
|
18
|
+
governed. A passing check over 40% of files is not success — Ark says so explicitly.
|
|
19
|
+
|
|
20
|
+
## Shapes map to presets, not ad-hoc folders
|
|
21
|
+
|
|
22
|
+
Every suggestion traces to `templates/architecture-playbook.json`, named presets, or
|
|
23
|
+
enthusiast policy packs. Agents must not invent `utils/` or `helpers/` as ungoverned dumping
|
|
24
|
+
grounds — classify via `/ark-contract`.
|
|
25
|
+
|
|
26
|
+
## When not to use enthusiast onboarding
|
|
27
|
+
|
|
28
|
+
Existing large codebases need `/ark-adopt` and the [brownfield playbook](../brownfield-adoption.md):
|
|
29
|
+
diagnose, fix the contract, freeze only real debt, burn down in order.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# How to install agent gates
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
npx ark-check --install-agent-gates
|
|
5
|
+
npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
|
|
6
|
+
```
|
|
7
|
+
|
|
8
|
+
Installs:
|
|
9
|
+
|
|
10
|
+
- Write-gate hook configuration (Claude / Grok PreToolUse; Cursor advisory + MCP)
|
|
11
|
+
- MCP server entry (`.mcp.json`, Cursor/Codex/Grok equivalents)
|
|
12
|
+
- `/ark-*` skills including **`/ark-architect`** and **`/ark-autopilot`**
|
|
13
|
+
|
|
14
|
+
| Host | Extra paths |
|
|
15
|
+
|------|-------------|
|
|
16
|
+
| Claude Code | `.claude/settings.json`, `.claude/skills/` |
|
|
17
|
+
| Cursor | `.cursor/mcp.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
|
|
18
|
+
| Codex | `docs/ark-codex-config.toml` + home MCP/prompts |
|
|
19
|
+
| **Grok Build** | `.grok/config.toml`, `.grok/hooks/`, `.grok/skills/` |
|
|
20
|
+
|
|
21
|
+
## Session hint
|
|
22
|
+
|
|
23
|
+
`ark-mcp --session-context` appends when governed coverage is low:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
New to Ark? Run /ark-architect or: ark-check --recommend
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Verify gates
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npx ark-check --doctor
|
|
33
|
+
npx ark-check --require-gates
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Full copy-paste setups: [docs/ai-gates.md](../ai-gates.md).
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# How to use a gallery starter
|
|
2
|
+
|
|
3
|
+
Gallery starters are minimal phase-1 scaffolds with a passing `ark-check --strict-config`.
|
|
4
|
+
|
|
5
|
+
## Copy a starter
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
cp -R path/to/ark/examples/crud-product-starter/. .
|
|
9
|
+
npm install
|
|
10
|
+
npm run check
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Pick by archetype — see [examples/README.md](../../examples/README.md).
|
|
14
|
+
|
|
15
|
+
## When to use a starter vs hexagonal-order-api
|
|
16
|
+
|
|
17
|
+
| Need | Use |
|
|
18
|
+
|------|-----|
|
|
19
|
+
| Fast baseline layout | `*-starter/` gallery |
|
|
20
|
+
| Runnable API + break exercises | `hexagonal-order-api/` |
|
|
21
|
+
|
|
22
|
+
## After copying
|
|
23
|
+
|
|
24
|
+
1. Run `ark-check --doctor`
|
|
25
|
+
2. Install gates: `ark-check --install-agent-gates`
|
|
26
|
+
3. Use `/ark-place` for new files
|
|
27
|
+
4. Optionally commit `ark-adoption-plan.json` from `--write-plan` alongside `ark.config.json`
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# How to pick your application shape
|
|
2
|
+
|
|
3
|
+
## Terminal
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx ark-check --recommend
|
|
7
|
+
npx ark-check --recommend --json
|
|
8
|
+
npx ark-check --recommend --write-plan # also writes ark-adoption-plan.json
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## MCP (agents)
|
|
12
|
+
|
|
13
|
+
Call tool **`ark_recommend`** — same JSON as `--recommend --json`.
|
|
14
|
+
|
|
15
|
+
## Skill
|
|
16
|
+
|
|
17
|
+
Run **`/ark-architect`** on a greenfield or early-adoption repo.
|
|
18
|
+
|
|
19
|
+
## What to read in the output
|
|
20
|
+
|
|
21
|
+
| Field | Meaning |
|
|
22
|
+
|-------|---------|
|
|
23
|
+
| `archetype` | Application shape id (`crud-product`, `api-backend`, …) |
|
|
24
|
+
| `preset` | Named Ark layout (`hexagonal`, `layered`, `feature-sliced`, `monorepo`) |
|
|
25
|
+
| `confidence` | How sure the scorer is from repo signals |
|
|
26
|
+
| `adoptInOrder.phase1` | Folders to create first |
|
|
27
|
+
| `analogy` | Plain-language mental model |
|
|
28
|
+
| `antiPatterns` | What Ark will block later |
|
|
29
|
+
| `firstCommand` | Usually `ark init --archetype <id> --yes` |
|
|
30
|
+
|
|
31
|
+
Framework names appear only as secondary `toolHints` in JSON — never as the archetype label.
|
|
32
|
+
|
|
33
|
+
## Low confidence?
|
|
34
|
+
|
|
35
|
+
If `confidence < 0.5`, ask:
|
|
36
|
+
|
|
37
|
+
1. Will this app save data between sessions?
|
|
38
|
+
2. Is this one app or several in one repository?
|
|
39
|
+
|
|
40
|
+
Then re-run `--recommend` or continue with `/ark-architect`.
|
|
41
|
+
|
|
42
|
+
## Reference
|
|
43
|
+
|
|
44
|
+
Full archetype table: [reference-archetypes.md](reference-archetypes.md). Source of truth:
|
|
45
|
+
`templates/architecture-playbook.json`.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# How to apply an enthusiast policy pack
|
|
2
|
+
|
|
3
|
+
Policy packs are thin enthusiast variants over the same preset factories as `ark init --preset`.
|
|
4
|
+
|
|
5
|
+
## List packs
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx ark-check --list-policy-packs
|
|
9
|
+
npx ark-check --list-policy-packs --json
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Available packs:
|
|
13
|
+
|
|
14
|
+
- `enthusiast-hexagonal`
|
|
15
|
+
- `enthusiast-layered`
|
|
16
|
+
- `enthusiast-feature-sliced`
|
|
17
|
+
- `enthusiast-monorepo`
|
|
18
|
+
|
|
19
|
+
## Apply
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npx ark-check --apply-policy-pack enthusiast-hexagonal
|
|
23
|
+
npx ark-check --root . --config ark.config.json --strict-config
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Use `--force` to overwrite an existing `ark.config.json`.
|
|
27
|
+
|
|
28
|
+
Monorepo packs detect workspace roots from `package.json` / `pnpm-workspace.yaml` the same way `--init --preset monorepo` does.
|
|
29
|
+
|
|
30
|
+
## Packs vs archetypes
|
|
31
|
+
|
|
32
|
+
| You know… | Start with |
|
|
33
|
+
|-----------|------------|
|
|
34
|
+
| Application shape (todo app, API, …) | `ark-check --recommend` → `ark init --archetype` |
|
|
35
|
+
| Preset name only | `--apply-policy-pack enthusiast-<preset>` |
|
|
36
|
+
|
|
37
|
+
`ark-adoption-plan.json` from `--write-plan` includes a suggested `policyPack` id matching the recommended preset.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Reference: archetypes and presets
|
|
2
|
+
|
|
3
|
+
Authoritative source: `templates/architecture-playbook.json` (shipped in the npm package).
|
|
4
|
+
|
|
5
|
+
## Archetypes (application shape)
|
|
6
|
+
|
|
7
|
+
| Id | Shape | Default preset |
|
|
8
|
+
|----|-------|----------------|
|
|
9
|
+
| `crud-product` | UI + stored data | `hexagonal` |
|
|
10
|
+
| `api-backend` | API server, no UI in repo | `hexagonal` |
|
|
11
|
+
| `frontend-surface` | UI-heavy; backend elsewhere | `layered` / `feature-sliced` |
|
|
12
|
+
| `library-sdk` | Publishable package | `layered` |
|
|
13
|
+
| `cli-utility` | Command-line tool | `layered` |
|
|
14
|
+
| `worker-pipeline` | Background jobs | `hexagonal` |
|
|
15
|
+
| `event-coordinator` | Multi-step processes | `hexagonal` |
|
|
16
|
+
| `integration-bridge` | System glue | `hexagonal` |
|
|
17
|
+
| `multi-app-workspace` | Monorepo | `monorepo` |
|
|
18
|
+
| `prototype-spike` | Quick experiment | `layered` |
|
|
19
|
+
|
|
20
|
+
## Named presets
|
|
21
|
+
|
|
22
|
+
| Preset | Policy pack |
|
|
23
|
+
|--------|-------------|
|
|
24
|
+
| `hexagonal` | `enthusiast-hexagonal` |
|
|
25
|
+
| `layered` | `enthusiast-layered` |
|
|
26
|
+
| `feature-sliced` | `enthusiast-feature-sliced` |
|
|
27
|
+
| `monorepo` | `enthusiast-monorepo` |
|
|
28
|
+
|
|
29
|
+
## Gallery mapping
|
|
30
|
+
|
|
31
|
+
| Archetype | Starter |
|
|
32
|
+
|-----------|---------|
|
|
33
|
+
| `crud-product` | `examples/crud-product-starter/` |
|
|
34
|
+
| `api-backend` | `examples/api-backend-starter/` |
|
|
35
|
+
| `worker-pipeline` | `examples/worker-pipeline-starter/` |
|
|
36
|
+
| `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Reference: commands and artifacts
|
|
2
|
+
|
|
3
|
+
## Recommendation
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
ark-check --recommend [--json] [--write-plan]
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
MCP: `ark_recommend` — same JSON body.
|
|
10
|
+
|
|
11
|
+
## Adoption plan artifact
|
|
12
|
+
|
|
13
|
+
`ark-adoption-plan.json` — optional committed record. Fields:
|
|
14
|
+
|
|
15
|
+
- `archetype`, `preset`, `confidence`
|
|
16
|
+
- `phases` (`1` | `2` | `3` layer lists) and `adoptInOrder.phase1|phase2|phase3`
|
|
17
|
+
- `matchedSignals` — shape signals that drove the score
|
|
18
|
+
- `analogy`, `antiPatterns`, `why`
|
|
19
|
+
- `initCommand`, `firstCommand`, `recommendCommand`, `checkCommand`
|
|
20
|
+
- `galleryStarter`, `policyPack`
|
|
21
|
+
|
|
22
|
+
Never weakens the gate; JSON only.
|
|
23
|
+
|
|
24
|
+
## Policy packs
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
ark-check --list-policy-packs [--json]
|
|
28
|
+
ark-check --apply-policy-pack <id> [--force]
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Pack metadata: `templates/policy-packs/enthusiast-*.json`.
|
|
32
|
+
|
|
33
|
+
## Init and verify
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
ark init --archetype <id> --yes
|
|
37
|
+
ark-check --doctor [--json]
|
|
38
|
+
ark-check --coverage [--json]
|
|
39
|
+
ark-check --strict-config
|
|
40
|
+
ark-check --report out.html --beginner
|
|
41
|
+
ark-check --watch
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Violation JSON (enthusiast fields)
|
|
45
|
+
|
|
46
|
+
When present on violations:
|
|
47
|
+
|
|
48
|
+
- `fixClass` — e.g. `port-inversion`, `file-move`
|
|
49
|
+
- `effort` — `small` | `medium`
|
|
50
|
+
- `enthusiastHint` — plain English fix guidance
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Tutorial: your first Ark-governed project
|
|
2
|
+
|
|
3
|
+
This tutorial walks one path end-to-end. You need Node 18+ and a new empty folder.
|
|
4
|
+
|
|
5
|
+
## 1. Create the project
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
mkdir my-app && cd my-app
|
|
9
|
+
npm init -y
|
|
10
|
+
npm install -D arkgate typescript
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## 2. Discover your application shape
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx ark-check --recommend
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Read the **archetype** (application shape, not “Next.js” or “Prisma”), the **preset**,
|
|
20
|
+
and **phase-1 layers**. If you are unsure, answer the two questions the agent skill
|
|
21
|
+
may ask: “Will this save data?” and “Is this one app or several in one repo?”
|
|
22
|
+
|
|
23
|
+
Optional machine-readable record:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx ark-check --recommend --write-plan
|
|
27
|
+
# -> ark-adoption-plan.json (safe to commit as a team adoption record)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## 3. Adopt the contract
|
|
31
|
+
|
|
32
|
+
Non-interactive (recommended for scripts):
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npx ark init --archetype crud-product --yes
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Or apply an enthusiast policy pack directly:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx ark-check --list-policy-packs
|
|
42
|
+
npx ark-check --apply-policy-pack enthusiast-hexagonal
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## 4. Scaffold phase-1 folders
|
|
46
|
+
|
|
47
|
+
Create only the directories listed under phase 1 — for a CRUD product typically:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
src/domain/
|
|
51
|
+
src/application/
|
|
52
|
+
src/presentation/ # or pages/, components/, http/
|
|
53
|
+
src/adapters/ # persistence implementations
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Or copy a [gallery starter](../enthusiast/how-to-gallery-starter.md) and run `npm install && npm run check`.
|
|
57
|
+
|
|
58
|
+
## 5. Install agent gates
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npx ark-check --install-agent-gates
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
This installs `/ark-architect`, `/ark-place`, `/ark-autopilot`, and the other `/ark-*` skills for Claude, Cursor, Codex, Grok, and other detected hosts.
|
|
65
|
+
|
|
66
|
+
## 6. Verify honestly
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npx ark-check --doctor
|
|
70
|
+
npx ark-check --coverage
|
|
71
|
+
npx ark-check --root . --config ark.config.json --strict-config
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Report `governed.percent` truthfully. An empty layer is fine; an ungoverned `lib/` folder is not.
|
|
75
|
+
|
|
76
|
+
## 7. Build a feature with the agent
|
|
77
|
+
|
|
78
|
+
Invoke `/ark-architect` once at the start, then `/ark-place` for each new file. The agent
|
|
79
|
+
should place use cases in `application/`, ports in `domain/`, and never import the database
|
|
80
|
+
into `domain/`.
|
|
81
|
+
|
|
82
|
+
## Next steps
|
|
83
|
+
|
|
84
|
+
- [How to pick your shape](how-to-pick-shape.md)
|
|
85
|
+
- [Public demos](../demos/)
|
|
86
|
+
- [Brownfield adoption](../brownfield-adoption.md) if you already have code
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Production Hardening
|
|
2
|
+
|
|
3
|
+
Ark's built-in stores are intentionally in-memory defaults. They are appropriate for tests,
|
|
4
|
+
local development, examples, and single-process demos. Production systems should provide
|
|
5
|
+
stores that match their durability, ordering, retention, and operational requirements.
|
|
6
|
+
|
|
7
|
+
## In-Memory Defaults
|
|
8
|
+
|
|
9
|
+
These defaults do not survive process restarts:
|
|
10
|
+
|
|
11
|
+
- `InMemoryAuditStore`
|
|
12
|
+
- `InMemoryOutboxStore`
|
|
13
|
+
- `InMemoryReadModelStore`
|
|
14
|
+
- `InMemoryWorkflowStore`
|
|
15
|
+
|
|
16
|
+
Use them only when losing state is acceptable.
|
|
17
|
+
|
|
18
|
+
## Production Store Checklist
|
|
19
|
+
|
|
20
|
+
When implementing Ark store interfaces in production, cover these guarantees explicitly:
|
|
21
|
+
|
|
22
|
+
- Durability: records survive process restarts and deploys.
|
|
23
|
+
- Idempotency: repeated writes or dispatch attempts do not corrupt state.
|
|
24
|
+
- Ordering: event/outbox ordering is defined where consumers depend on it.
|
|
25
|
+
- Concurrency: simultaneous publishers/workers cannot race checkpoints or workflow state.
|
|
26
|
+
- Retention: audit and trace records have an explicit retention policy.
|
|
27
|
+
- Observability: failed writes and dispatches are visible to operators.
|
|
28
|
+
- Migration: schema changes for stored records are versioned.
|
|
29
|
+
|
|
30
|
+
## Interface Targets
|
|
31
|
+
|
|
32
|
+
| Concern | Interface |
|
|
33
|
+
|---------|-----------|
|
|
34
|
+
| Audit records | `AuditStore` |
|
|
35
|
+
| Outbox dispatch handoff | `OutboxStore` |
|
|
36
|
+
| Projection state | `ReadModelStore` |
|
|
37
|
+
| Workflow snapshots | `WorkflowStore` |
|
|
38
|
+
|
|
39
|
+
## Example Shape
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
class DurableAuditStore implements AuditStore {
|
|
43
|
+
async append(record: AuditRecord): Promise<void> {
|
|
44
|
+
// Insert into your database with an idempotent key.
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
async query(query: AuditQuery = {}): Promise<AuditRecord[]> {
|
|
48
|
+
// Apply query filters and retention-aware ordering.
|
|
49
|
+
return [];
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
async clear(): Promise<void> {
|
|
53
|
+
// Usually only enabled in tests or isolated maintenance jobs.
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Ark does not ship a database adapter in core because storage choice is operationally
|
|
59
|
+
specific. Keep those adapters in the application or a separate integration package.
|
package/package.json
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "arkgate",
|
|
3
|
+
"version": "2.1.0",
|
|
4
|
+
"description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.cjs",
|
|
7
|
+
"module": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.js",
|
|
13
|
+
"require": "./dist/index.cjs"
|
|
14
|
+
},
|
|
15
|
+
"./eslint": {
|
|
16
|
+
"types": "./dist/eslint/index.d.ts",
|
|
17
|
+
"import": "./dist/eslint/index.js",
|
|
18
|
+
"require": "./dist/eslint/index.cjs"
|
|
19
|
+
},
|
|
20
|
+
"./nestjs": {
|
|
21
|
+
"types": "./dist/nestjs/index.d.ts",
|
|
22
|
+
"import": "./dist/nestjs/index.js",
|
|
23
|
+
"require": "./dist/nestjs/index.cjs"
|
|
24
|
+
},
|
|
25
|
+
"./package.json": "./package.json"
|
|
26
|
+
},
|
|
27
|
+
"bin": {
|
|
28
|
+
"arkgate": "bin/ark.mjs",
|
|
29
|
+
"arkgate-check": "bin/ark-check.mjs",
|
|
30
|
+
"arkgate-mcp": "bin/ark-mcp.mjs",
|
|
31
|
+
"ark": "bin/ark.mjs",
|
|
32
|
+
"ark-check": "bin/ark-check.mjs",
|
|
33
|
+
"ark-mcp": "bin/ark-mcp.mjs"
|
|
34
|
+
},
|
|
35
|
+
"mcpName": "io.github.pedroknigge/arkgate",
|
|
36
|
+
"files": [
|
|
37
|
+
"bin",
|
|
38
|
+
"dist",
|
|
39
|
+
"docs/agent-guide.md",
|
|
40
|
+
"docs/enthusiast",
|
|
41
|
+
"docs/demos",
|
|
42
|
+
"docs/ai-gates.md",
|
|
43
|
+
"docs/ark-check-example.json",
|
|
44
|
+
"docs/assets",
|
|
45
|
+
"docs/brownfield-adoption.md",
|
|
46
|
+
"docs/production-hardening.md",
|
|
47
|
+
"templates",
|
|
48
|
+
"server.json",
|
|
49
|
+
"README.md",
|
|
50
|
+
"CHANGELOG.md",
|
|
51
|
+
"SECURITY.md",
|
|
52
|
+
"LICENSE"
|
|
53
|
+
],
|
|
54
|
+
"scripts": {
|
|
55
|
+
"build": "tsup",
|
|
56
|
+
"dev": "tsup --watch",
|
|
57
|
+
"test": "vitest",
|
|
58
|
+
"test:run": "vitest run",
|
|
59
|
+
"typecheck": "tsc --noEmit",
|
|
60
|
+
"security:audit": "npm audit --omit=dev --audit-level=high",
|
|
61
|
+
"check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict-config",
|
|
62
|
+
"eval:agent": "node eval/run.mjs",
|
|
63
|
+
"eval:comparative": "node eval/comparative-run.mjs",
|
|
64
|
+
"clean": "rm -rf dist",
|
|
65
|
+
"release:npm": "node scripts/release-npm.mjs",
|
|
66
|
+
"prepack": "npm run build"
|
|
67
|
+
},
|
|
68
|
+
"peerDependencies": {
|
|
69
|
+
"@nestjs/common": ">=9"
|
|
70
|
+
},
|
|
71
|
+
"peerDependenciesMeta": {
|
|
72
|
+
"@nestjs/common": {
|
|
73
|
+
"optional": true
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
"overrides": {
|
|
77
|
+
"vite": "6.4.3",
|
|
78
|
+
"tsup": {
|
|
79
|
+
"esbuild": "0.28.1"
|
|
80
|
+
},
|
|
81
|
+
"bundle-require": {
|
|
82
|
+
"esbuild": "0.28.1"
|
|
83
|
+
}
|
|
84
|
+
},
|
|
85
|
+
"devDependencies": {
|
|
86
|
+
"@nestjs/common": "^11.1.27",
|
|
87
|
+
"@types/node": "^20.14.0",
|
|
88
|
+
"reflect-metadata": "^0.2.2",
|
|
89
|
+
"rxjs": "^7.8.2",
|
|
90
|
+
"tsup": "^8.1.0",
|
|
91
|
+
"typescript": "^5.5.3",
|
|
92
|
+
"vitest": "^3.2.6"
|
|
93
|
+
},
|
|
94
|
+
"engines": {
|
|
95
|
+
"node": ">=18"
|
|
96
|
+
},
|
|
97
|
+
"keywords": [
|
|
98
|
+
"arkgate",
|
|
99
|
+
"architecture",
|
|
100
|
+
"architecture-gate",
|
|
101
|
+
"ai-agents",
|
|
102
|
+
"mcp",
|
|
103
|
+
"write-gate",
|
|
104
|
+
"hexagonal",
|
|
105
|
+
"clean-architecture",
|
|
106
|
+
"layered-architecture",
|
|
107
|
+
"import-rules",
|
|
108
|
+
"dependency-rules",
|
|
109
|
+
"boundaries",
|
|
110
|
+
"co-pilot",
|
|
111
|
+
"governance",
|
|
112
|
+
"typescript",
|
|
113
|
+
"eslint",
|
|
114
|
+
"nestjs",
|
|
115
|
+
"architecture-enforcement"
|
|
116
|
+
],
|
|
117
|
+
"license": "MIT",
|
|
118
|
+
"repository": {
|
|
119
|
+
"type": "git",
|
|
120
|
+
"url": "git+https://github.com/pedroknigge/ark-runtime-kernel.git"
|
|
121
|
+
},
|
|
122
|
+
"publishConfig": {
|
|
123
|
+
"access": "public"
|
|
124
|
+
}
|
|
125
|
+
}
|