Skip to content

Commit 99d2475

Browse files
AdaInTheLabAdaInTheLab
authored
Merge pull request #3 from AdaInTheLab/scms/db-schema-migration-lab-notes
CORE [SCMS] establish contract-first HPL CLI read surface for Lab Notes 🧬
2 parents cc5bdd6 + 9ab5eaf commit 99d2475

23 files changed

Lines changed: 1123 additions & 1908 deletions

‎.github/RELEASE_TEMPLATE.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# HPL CLI v{{version}}
2+
3+
> Contract-first CLI release for **The Human Pattern Lab**
4+
> This release follows the same change classification and discipline as the Lab API.
5+
6+
---
7+
8+
## 🔎 Summary
9+
10+
Brief, high-signal description of what this CLI release delivers and **why it exists**.
11+
12+
Example:
13+
This release introduces the first contract-stable CLI interface for reading Lab Notes from the ledger-backed API, with explicit intent metadata and machine-parseable output.
14+
15+
---
16+
17+
## 📦 Compatibility
18+
19+
| Component | Version |
20+
|---------|--------|
21+
| **CLI package** | `{{version}}` |
22+
| **CLI schemaVersion** | `{{schemaVersion}}` |
23+
| **Compatible API versions** | `>= {{apiVersion}}` |
24+
25+
Compatibility is defined by the **CLI contract**, not by implementation details.
26+
27+
---
28+
29+
## 🚨 Breaking Changes
30+
31+
> Only include this section if applicable.
32+
33+
- Describe **what changed**
34+
- Describe **why it changed**
35+
- Describe **what users or agents must do**
36+
37+
Example:
38+
- CLI JSON output for `notes list` now nests results under `data.notes`
39+
(previously returned a top-level array)
40+
41+
Breaking changes **always** imply:
42+
- CLI `schemaVersion` bump
43+
- Explicit callout here
44+
- Compatibility table update
45+
46+
---
47+
48+
## ➕ Additive Changes
49+
50+
New functionality that does **not** break existing usage.
51+
52+
Example:
53+
- Added `notes get <slug>` command
54+
- Added `--limit` flag to `notes list`
55+
- Added intent metadata to all JSON outputs
56+
57+
Additive changes may bump the CLI package version, but **do not require** a contract bump.
58+
59+
---
60+
61+
## 🔧 Internal Changes
62+
63+
Refactors, fixes, or improvements that do not affect external behavior.
64+
65+
Example:
66+
- Refactored HTTP client to support raw and enveloped API responses
67+
- Improved Windows stability by removing hard process exits
68+
- Internal rendering utilities for deterministic terminal output
69+
70+
---
71+
72+
## 🧠 Contract Notes
73+
74+
This release maintains the following guarantees:
75+
76+
- All `--json` output conforms to `schemaVersion: {{schemaVersion}}`
77+
- Intent identifiers are stable and unchanged
78+
- Exit code meanings are unchanged
79+
80+
If this release introduces new intents, they are **additive** and documented below.
81+
82+
---
83+
84+
## 🎯 Supported Intents (Alpha Tier)
85+
86+
```
87+
show_version
88+
show_capabilities
89+
check_health
90+
render_lab_note
91+
```
92+
93+
Intent semantics are unchanged unless explicitly stated.
94+
95+
---
96+
97+
## 🧪 Validation
98+
99+
Recommended verification steps:
100+
101+
```bash
102+
hpl version --json
103+
hpl capabilities --json
104+
hpl health --json
105+
hpl notes list --json
106+
hpl notes get <slug> --json
107+
```
108+
109+
Successful execution confirms contract compatibility.
110+
111+
---
112+
113+
## 📚 Notes
114+
115+
- This CLI release aligns with the **Lab API release discipline**
116+
- v0.x does not imply instability — it implies **explicit governance**
117+
- Humans are a tolerated interface
118+
119+
---
120+
121+
## 🔗 References
122+
123+
- API Release: `{{apiReleaseLink}}`
124+
- CLI Contract: `schemaVersion {{schemaVersion}}`
125+
- Documentation: https://thehumanpatternlab.com/docs
126+
127+
---
128+
129+
🦊
130+
*The foxes are watching. The contract holds.*

‎README.md‎

Lines changed: 20 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,35 @@
1-
<!--
2-
Skulk CLI
3-
The Human Pattern Lab
1+
# HPL CLI (Alpha) 🧭🦊
42

5-
This README is written for humans.
6-
Design rationale lives in DESIGN.md.
7-
-->
8-
# Skulk CLI
3+
Contract-first CLI for The Human Pattern Lab.
94

10-
[![AI-Forward CLI](https://img.shields.io/badge/AI--Forward%20CLI-automation--safe%20by%20design-7c3aed?style=flat-square)](./DESIGN.md) ![Carmel Judgment](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml/badge.svg) ![npm](https://img.shields.io/npm/v/@thehumanpatternlab/skulk)
11-
12-
13-
> A modern, automation-safe CLI for The Human Pattern Lab.
14-
15-
Skulk is a command-line tool for syncing and managing Lab Notes — built to work just as well for humans at the keyboard as it does for automation, CI, and agent-driven workflows.
16-
17-
---
18-
## What Skulk Connects To
19-
20-
Skulk is the CLI for **The Human Pattern Lab API**.
21-
22-
By default it targets a Human Pattern Lab API instance. You can override the API endpoint with `--base-url` to use staging or a self-hosted deployment of the same API.
23-
24-
> Note: `--base-url` is intended for alternate deployments of the Human Pattern Lab API, not arbitrary third-party APIs.
25-
26-
---
27-
## Configuration
28-
29-
### Environment variables
30-
31-
- `SKULK_TOKEN` — API token used to authenticate requests.
32-
- `SKULK_BASE_URL` — Base URL for a Human Pattern Lab API instance (overridden by `--base-url`).
33-
34-
Example:
35-
36-
```bash
37-
export SKULK_TOKEN="..."
38-
export SKULK_BASE_URL="https://thehumanpatternlab.com/api"
39-
skulk notes sync --dir ./src/labnotes/en
40-
```
41-
---
42-
43-
## Why Skulk Exists
44-
45-
Command-line tools no longer live in a human-only world.
46-
47-
They’re run by:
48-
- developers exploring and iterating
49-
- scripts and CI pipelines
50-
- automation layers and AI-assisted workflows
51-
52-
Skulk was designed from the start to behave **predictably and honestly** in all of those contexts — without sacrificing human usability.
53-
54-
---
55-
56-
## 🤖 AI-Forward (for Humans)
57-
58-
Skulk follows **AI-forward engineering principles** — not for AIs, but for the people who build tools that increasingly interact with them.
59-
60-
### Dual Output Modes
61-
62-
By default, Skulk is human-readable:
5+
## Install (local dev)
636

647
```bash
65-
skulk notes sync
8+
npm install
9+
npm run dev -- --help
6610
```
6711

68-
When `--json` is enabled:
69-
70-
```bash
71-
skulk --json notes sync
72-
```
12+
## Config
7313

74-
Skulk switches to machine-readable output:
75-
- stdout contains **only valid JSON**
76-
- no banners, emojis, or progress chatter
77-
- errors go to stderr
78-
- exit codes are deterministic
14+
- `HPL_API_BASE_URL` (default: `https://api.thehumanpatternlab.com`)
7915

80-
This makes Skulk safe to use in:
81-
- scripts
82-
- CI pipelines
83-
- automation
84-
- AI-assisted workflows
16+
## Commands (MVP)
8517

86-
---
18+
- `hpl version`
19+
- `hpl capabilities`
20+
- `hpl health`
21+
- `hpl notes list [--limit N]`
22+
- `hpl notes get <slug> [--raw]`
8723

88-
## JSON Output Contract
24+
## JSON contract
8925

90-
Structured output is treated as a **contract**, not a courtesy.
26+
Add `--json` to emit machine-readable JSON only on stdout.
9127

92-
The repository includes a built-in verification:
28+
### Examples
9329

9430
```bash
95-
npm run json:check
31+
hpl capabilities --json
32+
hpl health --json
33+
hpl notes list --json
34+
hpl notes get the-invitation --json
9635
```
97-
98-
This command runs Skulk in `--json` mode and fails immediately if *any* non-JSON output appears on stdout.
99-
100-
---
101-
102-
## Design & Philosophy
103-
104-
Curious why Skulk works this way?
105-
→ [DESIGN.md](./DESIGN.md)
106-
107-
---
108-
109-
## Philosophy
110-
111-
> Automation shouldn’t require guessing what a tool *meant* to say.
112-
113-
Skulk is boring in the best way:
114-
predictable, explicit, and dependable.

0 commit comments

Comments
 (0)