@deepdockai/cli 0.0.0-stage → 1.0.0

package/skill/references/example-integration.md

@@ -0,0 +1,159 @@
+# Worked example: the clients and one flow
+
+Two full, tested clients ship with this skill; every other language gets `curl` below and ports
+one of the two. Each client does the four things the OpenAPI document cannot tell you: the bearer
+header, the envelope unwrap, the `Idempotency-Key` header with replay detection, and a typed error
+carrying the code. Both also carry `attempt()`, one try of a persisted pending write that returns
+the row's new status. Field names in the flow below are illustrative: read them from the live
+document for your system.
+
+| Language | File | Needs |
+|---|---|---|
+| TypeScript | [clients/deepdock.ts](clients/deepdock.ts) | `fetch` (Node 18+, Bun, Deno, browsers); no dependencies |
+| Python | [clients/deepdock.py](clients/deepdock.py) | Python 3.9+, `httpx` |
+| anything else | the `curl` calls below | port either client, keeping its shape |
+
+Copy the file into the project; do not reach into the skill directory at runtime.
+
+## What the clients give you
+
+```ts
+import { Deepdock, DeepdockError, DeepdockTransportError, attempt, type PendingWrite } from './deepdock'
+
+const dd = new Deepdock(process.env.DEEPDOCK_API_KEY!)          // 30 s timeout by default
+const page = await dd.read<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' }, { limit: 50 })
+for await (const p of dd.readAll<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' })) { /* every page */ }
+const { data, replayed } = await dd.write<{ noteId: number }>(deviceId, 'example-erp', 'createNote', 'POST', key, input)
+const systems = await dd.systems(deviceId)                      // live; can throw device_offline
+const device = await dd.pair('K7Q-4MX', 'Demo')                 // keep device.id
+```
+
+```python
+from deepdock import Deepdock, DeepdockError, DeepdockTransportError, PendingWrite, attempt
+
+dd = Deepdock(os.environ["DEEPDOCK_API_KEY"])
+page = dd.read(device_id, "example-erp", "searchNotes", {"text": "TEST-DEEPDOCK-"}, limit=50)
+res = dd.write(device_id, "example-erp", "createNote", "POST", key, body)   # res.data, res.replayed
+```
+
+Errors: `DeepdockError` has `status`, `code`, `requestId`, `systems`; switch on `code`
+([errors.md](errors.md)). `DeepdockTransportError` means no answer or not Deepdock's envelope
+(timeout, network, a proxy page): for a write, retry with the same key.
+
+## Sending a write: persist first, then one attempt at a time
+
+Persist the pending write (key, device, action, method, input, status) **before** the first send,
+so a crash between send and answer cannot produce a second record under a new key. `attempt()`
+moves the row to `done`, `sent` (retry later, same key), `unknown` (read back before anything
+else) or `refused` (nothing was written; a changed input gets a new key). A job retries `sent`
+rows with backoff: seconds, then minutes, for hours if the device stays offline.
+
+```ts
+const row: PendingWrite = {
+  key: `order-${order.id}-create-note`, // 8 to 128 chars of A-Z a-z 0-9 _ -, stable per business event
+  deviceId, system: 'example-erp', action: 'createNote', method: 'POST',
+  input, status: 'pending', conflictRetries: 0,
+}
+await store.save(row)                      // before the first send
+const next = await attempt(dd, row)        // one try
+await store.save(next)                     // the job picks up 'sent' rows later
+```
+
+## One flow: create a record on the demo device and read it back
+
+```ts
+import { randomUUID } from 'node:crypto'
+import { Deepdock, attempt, type PendingWrite } from './deepdock'
+
+const dd = new Deepdock(process.env.DEEPDOCK_API_KEY!)
+const deviceId = process.env.DEEPDOCK_TEST_DEVICE!   // the demo device the human named
+const system = 'example-erp'
+type Note = { noteId: number; text: string }
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export const run = async (store: { save: (row: PendingWrite) => Promise<void> }) => {
+  const marker = `TEST-DEEPDOCK-${randomUUID().replaceAll('-', '').slice(0, 6).toUpperCase()}`
+  let row: PendingWrite = {
+    key: `demo-${marker}-create`, deviceId, system, action: 'createNote', method: 'POST',
+    input: { text: marker, orderNumber: '1001' },
+    status: 'pending', conflictRetries: 0,
+  }
+  await store.save(row)
+
+  // The demo retries inline a few times; a product retries from the store in a job.
+  for (let delay = 2_000; row.status === 'pending' || row.status === 'sent'; delay = Math.min(delay * 2, 60_000)) {
+    row = await attempt(dd, row)
+    await store.save(row)
+    if (row.status === 'sent') await sleep(delay)
+  }
+  if (row.status === 'refused') throw new Error(`refused: ${row.refusedCode}`)
+
+  if (row.status === 'unknown') {
+    // Read back before deciding: the write may have landed.
+    const page = await dd.read<Note>(deviceId, system, 'searchNotes', { text: marker })
+    const landed = page.items.find((p) => p.text === marker)
+    if (!landed) throw new Error('write did not land; resend under a NEW key from the store')
+    row = { ...row, status: 'done', result: { noteId: landed.noteId } }
+    await store.save(row)
+  }
+
+  const created = row.result as { noteId: number }
+  const page = await dd.read<Note>(deviceId, system, 'searchNotes', { text: marker })
+  if (!page.items.some((p) => p.noteId === created.noteId)) throw new Error('created record not found by search')
+
+  // Cleanup list for the PR: record id, device, time.
+  console.log(`CREATED ${system} noteId=${created.noteId} on device ${deviceId} at ${new Date().toISOString()}`)
+}
+```
+
+## curl, for any other language
+
+```bash
+BASE=https://api.deepdock.ai
+AUTH="Authorization: Bearer $DEEPDOCK_API_KEY"
+
+# Pair a device (keep data.id)
+curl -sS -X POST "$BASE/v1/devices" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"code":"K7Q-4MX","label":"Demo"}'
+
+# The device's systems and action states (live; can answer device_offline)
+curl -sS "$BASE/v1/devices/$DEVICE/systems" -H "$AUTH"
+
+# The action index (your assigned actions, with schemas)
+curl -sS "$BASE/v1/devices/$DEVICE/systems/example-erp/actions" -H "$AUTH"
+
+# A read, paged: pass data.nextCursor back as cursor
+curl -sS "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchNotes?text=TEST-DEEPDOCK-&limit=50" -H "$AUTH"
+
+# A create: new Idempotency-Key per intended write, the same on every retry; 201, or 200 with
+# Idempotent-Replayed: true on a replay (-i shows the headers)
+curl -sS -i -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/createNote" \
+  -H "$AUTH" -H "Idempotency-Key: demo-$(date +%s)-create" -H 'Content-Type: application/json' \
+  -d '{"text":"TEST-DEEPDOCK-K3M9QA","orderNumber":"1001"}'
+
+# An update: PATCH, same rules
+curl -sS -i -X PATCH "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/updateNote" \
+  -H "$AUTH" -H "Idempotency-Key: demo-$(date +%s)-update" -H 'Content-Type: application/json' \
+  -d '{"noteId":"1001","text":"TEST-DEEPDOCK-K3M9QA edited"}'
+
+# Release a device
+curl -sS -X DELETE "$BASE/v1/devices/$DEVICE" -H "$AUTH"
+```
+
+A port in another language keeps the clients' shape: one `send` that sets the bearer header,
+parses the envelope, throws a typed error with `code` on `{ error }` and a transport error on no
+answer or non-JSON; `read` with `limit` and `cursor`; `write` with `Idempotency-Key` and the
+`Idempotent-Replayed` header; `attempt` over a persisted pending write.
+
+## Mapping the user's intent to a call (checklist)
+
+1. Which device? From your product's configuration for that customer site; never from the
+   user's free text.
+2. Is the action active? `systems()` once per session; show paused features as paused.
+3. Which action and method? From the stored index for that system.
+4. Does the write need a reference (author user, open case, record id)? Read it first.
+5. Build the input as strings; validate against the schema (`pattern`, `minLength`, `maxLength`,
+   `enum`) before sending so the user sees the rule where they typed.
+6. Choose the idempotency key from your business event and persist it with the pending write.
+7. Send; map the code with the reaction table; show the user the right sentence.
+8. Store the returned id as the system gave it.

package/skill/references/idempotency.md

@@ -0,0 +1,97 @@
+# Idempotency for writes
+
+Every `POST` or `PATCH` to an action carries an `Idempotency-Key` header. Without it the request is
+refused with `400 invalid_request`.
+
+## The key
+
+- 8 to 128 characters from `A-Z a-z 0-9 _ -`.
+- **One key per intended write.** Derive it from your own business event (an order id, a form
+  submission id, a job id plus the action name), or generate a UUID and persist it with the pending
+  write before sending. The key must survive a crash of your process, or a restart will write twice.
+- **The same key for every retry of that write.** Never regenerate it on retry.
+- Keys are remembered **per device**. The same key on another device is a different write.
+- A successful key is remembered for at least 7 days.
+- A write that was refused before anything was written (`invalid_input`, `target_rejected`, an
+  action-specific 422 such as `unknown_author`, `not_found`) or undone (`check_failed`) frees its
+  key: you may retry with the same key. After changing the input, use a new key; the old one may
+  still be remembered with the old input. `idempotency_conflict` does **not** free a key.
+
+## What a repeat answers
+
+| Situation | Answer |
+|---|---|
+| same key, same input, earlier write succeeded | `200` with the original `data` and `Idempotent-Replayed: true`; nothing written again |
+| same key, different input | `409 idempotency_conflict` |
+| same key, the earlier write is still running | `409 idempotency_conflict`; wait, then retry with the same key and input |
+| same key, the earlier write's outcome is unknown | `409 idempotency_conflict`; the key stays blocked |
+
+The three `idempotency_conflict` causes share one code and `message` is not to be parsed. One rule
+covers all three: retry with the same key and the same input a bounded number of times with
+backoff (a running write finishes within seconds); if it still conflicts, treat it as
+`outcome_unknown` below.
+
+Treat a replayed `200` as success. Read the header if you need to know it was a replay, for
+example to avoid double-logging.
+
+## The three outcomes you must plan for
+
+### `503 device_offline` on a write
+
+The device did not answer within 20 seconds, or was not connected. **The write may still have
+landed.** Retry with the **same key**: you get either the stored result (replayed) or a fresh run,
+never two writes. Back off between retries (seconds, then minutes); a device can be off for hours,
+so the retry runs from the persisted pending write in a job or queue, not inside the request that
+started it. A client-side timeout or a network failure on a write is the same case: same key.
+
+### `500 outcome_unknown`
+
+The customer's system did not confirm the write. Deepdock cannot tell whether it landed. The key is
+blocked: any reuse answers `409 idempotency_conflict`.
+
+Do not write again under a new key until you know. Read the record back with a read action (for a
+create, search by the value you wrote; for an update, read the record by id) and decide:
+
+- found with the written values: treat as done, record it, move on;
+- not found: write again under a **new** key;
+- cannot tell (the read action does not expose the field): stop and hand the case to a human with
+  the record identifiers.
+
+### `409 check_failed`
+
+The write was undone because its result did not match, and the action is now paused. Do not retry;
+the next calls answer `503 action_paused` until Deepdock resumes it. Tell the user the change was not
+saved.
+
+## Persisting state
+
+A robust integration keeps, per intended write: the idempotency key, the device id, the action, the
+input, a status (`pending`, `sent`, `done`, `unknown`, `refused`) and the result. Transitions:
+
+```
+pending ──send──▶ sent ──2xx (fresh or replayed)──────────────▶ done
+                   │  ──device_offline, timeout, network error, target_busy, temporarily_unavailable, internal_error ▶ sent  (retry later, same key)
+                   │  ──idempotency_conflict, retries left ───▶ sent     (retry, same key, same input)
+                   │  ──idempotency_conflict, retries spent ──▶ unknown  (read back before anything else)
+                   │  ──outcome_unknown ──────────────────────▶ unknown  (read back before anything else)
+                   │  ──invalid_input, target_rejected, action-specific 422, not_found, check_failed ▶ refused  (key is free; new input gets a new key)
+                   │  ──action_paused, system_unavailable ────▶ sent     (retry once the action is active again)
+```
+
+## Example
+
+```ts
+const key = `order-${order.id}-create-note` // stable per business event, 8 to 128 chars
+
+const res = await fetch(url, {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${apiKey}`,
+    'Idempotency-Key': key,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify(input),
+  signal: AbortSignal.timeout(30_000),
+})
+const replayed = res.headers.get('Idempotent-Replayed') === 'true'
+```

package/skill/references/testing.md

@@ -0,0 +1,80 @@
+# Testing safely
+
+Actions reach a real installation of the customer's system: the device you name is the one that
+gets written to. These rules are not optional.
+
+## The test device
+
+- Test against **a demo device of your own**: a Windows machine with the same system installed as
+  your customers run, with the Deepdock client paired to your organisation, and invented, marked
+  data on it.
+- **Never run a write against a device the human has not named as the test device.** If no device
+  has been named, ask. Do not pick the first device from `devices list`; it may be a live customer.
+- Pin the demo device's UUID in an environment variable (`DEEPDOCK_TEST_DEVICE`) and refuse to run
+  tests without it.
+
+## Test data
+
+- Invented values only: no real customer, employee or address data, even "just one row",
+  even from a screenshot. A fixture is copied into every clone and CI log for ever.
+- Every record you create carries the marker **`TEST-DEEPDOCK-<6 random characters>`** in its
+  name-like field (surname, company name), so it can be found and removed. Keep the marker through
+  updates: when you test a name update, write a second `TEST-DEEPDOCK-...` value.
+- Other fields take short values valid for their schema rule: a real past date, the first enum
+  member, `1001` for an order number, `Beispielstadt` for a city.
+- Keep the system's own text rules in mind: the OpenAPI document's field patterns and descriptions
+  say what a text field accepts; stick to plain Latin letters in test values.
+
+## Cleanup
+
+No action deletes anything. So:
+
+1. Every test run prints what it created: record id, device, time, and how many change-log entries
+   the updates added. The CLI runs no action, so your own test prints this.
+2. Paste the list into the PR or the task that created it, with an owner and a date by which it is
+   removed.
+3. The partner removes the records through the system's own user interface on the demo machine, or
+   resets the machine from a snapshot. Change-log entries stay until the reset.
+
+## The loop your test runs
+
+The CLI runs no action, so this loop is your code's, against the demo device:
+
+1. `deepdock devices systems <device> --org <slug> --json`: the system is running and every action
+   you need is active; otherwise stop and read the pause reason and `deepdock incidents list`.
+2. **Create** with a fresh idempotency key and `TEST-DEEPDOCK-` names: expect `201` and an id.
+3. **Replay** the same request with the same key: expect `200`, `Idempotent-Replayed: true`, no
+   second record.
+4. **Update** each update action once against that id, a new key each, changed values of the same
+   shape (a name update writes a second `TEST-DEEPDOCK-` name).
+5. **Read back** with the last written name as the search term: expect the id with the updated
+   values.
+6. Print the cleanup list.
+
+The proof is your client; the CLI only shows what the device offers.
+
+## Keys during development
+
+- Run `deepdock keys create "<project> dev" --expires 30d --write-env .env.local --org <slug>`.
+  A human approves it in the browser; the CLI writes the key into the file and keeps no copy.
+  Neither you nor the human sees the value; you work with its id, prefix and file name only.
+- Never ask for, read, print, echo, log or commit a key value. Use the key only against the demo
+  device.
+- It reaches every device of the organisation until it expires or is revoked. Tell the human to
+  revoke it when the integration ships and to create the live key with the same flow from their
+  own CLI.
+
+## Logs and prompts
+
+- Never log an action's `input` or a read's `items` in your running product: they are the customer's
+  records. Log the device id, the action, the code and the request id.
+- Never paste real records into an agent prompt or a ticket. Use the `TEST-DEEPDOCK-` records from
+  the demo device when you need a concrete example.
+
+## Unit tests of your client
+
+Mock the HTTP layer with the shapes from the OpenAPI document and this skill: `{ data }`,
+`{ error: { code } }`, `Idempotent-Replayed: true`, a `503 device_offline` on a write followed by
+a replayed `200`, a `500 outcome_unknown` followed by a read back. Cover every row of
+[errors.md](errors.md) your product reacts to. Do not record real responses from a customer
+device into fixtures.