@khotan/cli 0.12.0 → 1.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.
Files changed (3) hide show
  1. package/README.md +35 -48
  2. package/dist/khotan.js +595 -17644
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -24,32 +24,6 @@ bun run khotan -- --help # via the root script
24
24
  bun packages/khotan-cli/src/bin/khotan.ts --help # directly
25
25
  ```
26
26
 
27
- ## Scaffold a workspace
28
-
29
- `khotan init` writes Khotan agent integration into the current directory so your
30
- own agents (Cursor, Devin, …) can drive setup. It is non-destructive and
31
- re-runnable, and never writes secrets.
32
-
33
- ```bash
34
- khotan init # Cursor: .cursor/rules/khotan.mdc
35
- khotan init --client generic # khotan-agents.md
36
- khotan init --force # regenerate managed assets, overwriting edits
37
- khotan init --json # machine-readable summary on stdout
38
- ```
39
-
40
- It writes agent guidance for using the CLI. Authenticate separately with
41
- `khotan auth set-key` or environment variables — never commit a key.
42
-
43
- `init` also installs catalog-derived agent **skills** for using the CLI into
44
- `.cursor/skills/`, `.agents/skills/`, and `.claude/skills/` (regardless of
45
- `--client`): an overview `khotan` skill plus one per command domain
46
- (`khotan-apps`, `khotan-databases`, …). The skills are generated from the same
47
- capability catalog that drives the commands and `khotan help`, so they can
48
- never drift. They are **managed assets**: every `khotan init` run regenerates
49
- them in place (no `--force` needed), so re-running `init` is how a workspace
50
- picks up new CLI commands — like the `databases branches` group. Your
51
- hand-authored rule/guide stays non-destructive (preserved unless `--force`).
52
-
53
27
  ## Authentication & profiles
54
28
 
55
29
  The CLI authenticates with an organization-scoped **API key**. Credentials are
@@ -92,12 +66,12 @@ khotan apps list --profile staging # one-off override
92
66
  Environment variables take precedence over stored profile values, so no on-disk
93
67
  state is needed in CI or sandboxes:
94
68
 
95
- | Variable | Purpose |
96
- | ----------------- | ----------------------------------------- |
97
- | `KHOTAN_API_URL` | API origin (e.g. `https://app.example.com`) |
98
- | `KHOTAN_API_KEY` | Organization-scoped API key |
99
- | `KHOTAN_PROFILE` | Select a stored profile by name |
100
- | `KHOTAN_ORG_ID` | Expected org id; the CLI asserts `whoami.organizationId` matches it and fails closed otherwise |
69
+ | Variable | Purpose |
70
+ | ---------------- | ---------------------------------------------------------------------------------------------- |
71
+ | `KHOTAN_API_URL` | API origin (e.g. `https://app.example.com`) |
72
+ | `KHOTAN_API_KEY` | Organization-scoped API key |
73
+ | `KHOTAN_PROFILE` | Select a stored profile by name |
74
+ | `KHOTAN_ORG_ID` | Expected org id; the CLI asserts `whoami.organizationId` matches it and fails closed otherwise |
101
75
 
102
76
  ```bash
103
77
  export KHOTAN_API_URL=https://app.example.com
@@ -105,17 +79,17 @@ export KHOTAN_API_KEY=khk_live_...
105
79
  khotan apps list --json | jq '.apps[].id'
106
80
  ```
107
81
 
108
- ### Repo-local org isolation (`env.khotan.local`)
82
+ ### Repo-local org isolation (`.env.khotan.local`)
109
83
 
110
- When an `env.khotan.local` file sits at (or above) the working directory, the CLI
84
+ When an `.env.khotan.local` file sits at (or above) the working directory, the CLI
111
85
  auto-loads its `KHOTAN_*` values so every command is scoped to that repo's
112
86
  organization — never a stray machine-global profile from another customer. The
113
87
  file is authoritative: its values win over shell-exported `KHOTAN_*`, which win
114
88
  over the stored profile, and CLI flags win over everything (`flag >
115
- env.khotan.local > shell env > profile`).
89
+ .env.khotan.local > shell env > profile`).
116
90
 
117
91
  ```bash
118
- # env.khotan.local (git-ignored; never commit secrets)
92
+ # .env.khotan.local (git-ignored; never commit secrets)
119
93
  KHOTAN_API_URL='https://<customer>.khotan.com'
120
94
  KHOTAN_API_KEY='<org-scoped key>'
121
95
  KHOTAN_ORG_ID='<org id>'
@@ -126,23 +100,36 @@ When `KHOTAN_ORG_ID` (or `--assert-org <id>`) is set, every operation verifies
126
100
  mismatch (`error [org_mismatch]`). With no expected org id set, behavior is
127
101
  unchanged.
128
102
 
103
+ ## Workspace freshness
104
+
105
+ Run `khotan workspace check --json` to fetch and compare `origin/main` with the
106
+ current checkout. It reports the relation, commit counts, dirty state, and
107
+ whether a mutation must stop.
108
+
109
+ The CLI blocks catalog write and destructive commands from a Khotan workspace
110
+ that is behind, diverged, or unverifiable. A dirty or ahead checkout produces a
111
+ warning. The check updates remote-tracking metadata only; it never changes
112
+ local commits, the index, or worktree files.
113
+
129
114
  ## Command surface
130
115
 
131
116
  Commands are grouped by domain and derived from the capability catalog, so the
132
117
  documented surface and the executable surface cannot drift. Run `khotan help` or
133
118
  `khotan <command> --help` for details.
134
119
 
135
- | Domain | Examples |
136
- | --------- | -------- |
137
- | Apps | `apps list`, `apps get <id>`, `apps create --name web --env KEY=VALUE`, `apps delete <id>`, `apps redeploy <id>` |
138
- | App env | `apps env list <id>`, `apps env set <id> <KEY> --value V`, `apps env reveal <id> <KEY>`, `apps env unset <id> <KEY>`, `apps env bulk-set <id> --var A=1 --var B=2` |
139
- | Pipelines | same shape as apps under `pipelines …` |
140
- | Databases | `databases list`, `databases create --name db`, `databases connection <id>`, `databases rotate-credentials <id>`, `databases delete <id>` |
141
- | Files | `files list`, `files get <id>`, `files upload <path>`, `files download <id> --output <path>`, `files download-url <id>`, `files preview-url <id>`, `files update <id> --name new.txt`, `files delete <id>` |
142
- | Folders | `folders list`, `folders create --name docs`, `folders rename <id> --name new`, `folders delete <id>` |
143
- | Context | `context list`, `context get <slug>`, `context raw <slug>`, `context create --title T --kind knowledge --content '...' --folder-id <id>`, `context update <slug> --expected-revision 3 --content '...' --folder-id <id>`, `context delete <slug>` |
144
- | Context folders | `context folders list`, `context folders create --name docs --parent-id <id>`, `context folders update <id> --name new --parent-id <id>`, `context folders delete <id> --recursive` |
145
- | Context revisions | `context revisions list <slug>`, `context revisions get <slug> <revision>`, `context revisions restore <slug> <revision>` |
120
+ | Domain | Examples |
121
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
122
+ | Workspace | `workspace check`, `status`, `status --write` |
123
+ | Apps | `apps list`, `apps get <id>`, `apps create --name web --env KEY=VALUE`, `apps delete <id>`, `apps redeploy <id>` |
124
+ | App env | `apps env list <id>`, `apps env set <id> <KEY> --value V`, `apps env reveal <id> <KEY>`, `apps env unset <id> <KEY>`, `apps env bulk-set <id> --var A=1 --var B=2` |
125
+ | Pipelines | same shape as apps under `pipelines …` |
126
+ | Databases | `databases list`, `databases create --name db`, `databases connection <id>`, `databases rotate-credentials <id>`, `databases delete <id>` |
127
+ | Buckets | `buckets list`, `buckets get <id>`, `buckets create --name uploads [--idempotency-key <k>]`, `buckets credentials <id>`, `buckets delete <id>` |
128
+ | Files | `files list`, `files get <id>`, `files upload <path>`, `files download <id> --output <path>`, `files download-url <id>`, `files preview-url <id>`, `files update <id> --name new.txt`, `files delete <id>` |
129
+ | Folders | `folders list`, `folders create --name docs`, `folders rename <id> --name new`, `folders delete <id>` |
130
+ | Context | `context list`, `context get <slug>`, `context raw <slug>`, `context create --title T --kind knowledge --content '...' --folder-id <id>`, `context update <slug> --expected-revision 3 --content '...' --folder-id <id>`, `context delete <slug>` |
131
+ | Context folders | `context folders list`, `context folders create --name docs --parent-id <id>`, `context folders update <id> --name new --parent-id <id>`, `context folders delete <id> --recursive` |
132
+ | Context revisions | `context revisions list <slug>`, `context revisions get <slug> <revision>`, `context revisions restore <slug> <revision>` |
146
133
 
147
134
  ### Output modes
148
135
 
@@ -158,7 +145,7 @@ Each capability has a safety class (`read`, `write`, `destructive`, `secret`):
158
145
  - **Destructive** commands (`delete`, `env unset`) prompt for confirmation in a
159
146
  terminal and **refuse** in non-interactive sessions unless you pass `--yes`.
160
147
  - **Secret** values (`env reveal`, `databases connection`,
161
- `databases rotate-credentials`) are only available via explicit commands and
148
+ `databases rotate-credentials`, `buckets credentials`) are only available via explicit commands and
162
149
  are never included in list/table output.
163
150
 
164
151
  ### File transfer