@oddington/cli 0.1.62 → 0.1.63

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 +47 -29
  2. package/dist/os.js +425 -366
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -406,6 +406,26 @@ and other CLI output never reveal saved credentials.
406
406
  `OS_CONNECTION_CREDENTIAL`. Only run trusted code, and do not print or
407
407
  retain that value.
408
408
 
409
+ ## Add a routine
410
+
411
+ Inside your existing workspace repository, choose a routine name:
412
+
413
+ ```sh
414
+ os routine add invoice-summary
415
+ ```
416
+
417
+ This creates `routines/invoice-summary/routine.ts` and its package file, installs
418
+ dependencies without package scripts, and validates the new definition. The
419
+ starter returns `Hello world`; edit it to do your work. Existing files and the
420
+ workspace SDK version are preserved. Names use 1–63 lowercase letters, numbers
421
+ or hyphens, starting with a letter or number; reserved names are rejected.
422
+
423
+ The command finishes by showing `os routine run invoice-summary`. It does not
424
+ run or deploy the routine. OS sign-in and workspace access are checked when you
425
+ run it. If installation fails, your new files stay in place with exact recovery
426
+ commands. This command requires an existing `routines/package.json` workspace;
427
+ it does not create a repository or set up a new workspace.
428
+
409
429
  ## Check routine requirements
410
430
 
411
431
  ```sh
@@ -502,7 +522,7 @@ TypeScript publishers install `@oddington/sdk` and import the authoring helpers
502
522
  from its package root:
503
523
 
504
524
  ```ts
505
- import { defineHandler, resolveAsk, routinePublicationClient } from '@oddington/sdk';
525
+ import { data, defineHandler, resolveAsk, routinePublicationClient } from '@oddington/sdk';
506
526
 
507
527
  const inbox = routinePublicationClient();
508
528
  ```
@@ -515,14 +535,19 @@ perform no publishing on import. Accepted answers durably queue managed handlers
515
535
  without a browser start request. Handlers use preserved View inputs and guarded
516
536
  shared record capabilities. Digests have personal Mark as read receipts.
517
537
 
518
- Publishing routines capture committed records for review through the same client:
538
+ Routines read Records through Data and prepare guarded Changes:
519
539
 
520
540
  ```ts
521
- const captured = await inbox.readRecords({
522
- repository: 'general', refs: selectedRefs, atCommit: preparationCommit,
523
- })
541
+ const repository = data.repository('general');
542
+ const records = await repository.records.read(selectedRefs);
543
+ const changes = repository.changes();
544
+ changes.update(records[0], { status: 'ready' });
545
+ await changes.publish();
524
546
  ```
525
547
 
548
+ Local Runs read their own successive proposals and leave ordinary uncommitted
549
+ Record files for review. Explicit `os routine publish` sends the logical journal.
550
+
526
551
  OS intersects the routine's declared access with configured workspace
527
552
  capabilities. A new routine runs locally from a customer branch without
528
553
  registration, a merge to main, or deployment. The canonical ID is the `id` you
@@ -534,6 +559,15 @@ os routine run invoice-import --input input.json
534
559
  os routine run invoice-import --input - --json
535
560
  ```
536
561
 
562
+ If an existing local draft is missing its package file or dependency setup,
563
+ an interactive `run` can offer to create the minimal package file and install
564
+ dependencies in `routines/`, without running package scripts. It preserves
565
+ existing authored files and the declared SDK version. After validating the
566
+ definition, it prints the exact original run command; setup does not start the
567
+ routine automatically. JSON, non-interactive, remote, help and `check` commands
568
+ never perform this setup. Ambiguous drafts and undeclared runtime dependencies
569
+ require an explicit authored fix rather than a guessed package file.
570
+
537
571
  OS resolves the worktree's stable source identity and the canonical `defineRoutine`
538
572
  export in `routine.ts`. JSON input is validated before business work; its file/stdin
539
573
  path is transport, not business input. Omitted input uses the definition's default,
@@ -602,11 +636,11 @@ For modern local execution, install the workspace separately with Bun 1.3.14.
602
636
  For a failed local Run, the terminal and JSON result identify its failed step
603
637
  and known SDK error. Device-local `~/.os/<workspace>/runs/<run-id>/execution.json`
604
638
  retains redacted exception messages, stacks, causes and failed OS operations.
605
- Those details are not returned through app summaries. Use SDK 0.1.34 and CLI
606
- 0.1.62 for this evidence; updating only the CLI does not replace the SDK frozen
639
+ Those details are not returned through app summaries. Use SDK 0.1.35 and CLI
640
+ 0.1.63 for this evidence; updating only the CLI does not replace the SDK frozen
607
641
  into a customer routine or an earlier saved Run.
608
642
 
609
- Keep an exact stable `@oddington/sdk` 0.1.x patch through 0.1.34 in root
643
+ Keep an exact stable `@oddington/sdk` 0.1.x patch through 0.1.35 in root
610
644
  `devDependencies`, with its declaration, lock and installed package agreeing.
611
645
  Use compatible Node, the selected private ESM manifest and the shared frozen
612
646
  lock. OS verifies only the selected installed graph, stages its confined bytes
@@ -687,29 +721,13 @@ and item identities. Confirmed receipts need no second owning-capability call. A
687
721
  leaves `preparing.lock`; inspect its recorded PID and root before removing a
688
722
  stale lock, and never remove a live owner's lock.
689
723
 
690
- Installed write grants authorize guarded preparation through
691
- `inbox.repository.updateRecords`. Routines and managed response handlers that
692
- create records use
693
- `inbox.repository.writeRecords`; one request
694
- may combine schema-validated creations with guarded updates and returns the same
695
- authoritative repository receipt. Routine calls supply their stable request
696
- key; a response handler uses its durable execution identity instead.
697
- `inbox.repository.deleteRecords` accepts only
698
- reviewed refs and versions; it atomically refuses stale records and links from
699
- outside the deletion batch.
700
- Handler writes use that installation independently of the responder's identity.
724
+ Installed write grants authorize Data `changes()` for routine Record creates,
725
+ updates and deletions. The runtime owns retry identity. `routinePublicationClient()`
726
+ publishes Inbox work and has no Record methods. Managed Response handlers retain
727
+ their separately injected repository capability and durable execution identity;
728
+ handler writes use their installation independently of the responder's identity.
701
729
  Customer executable handlers still require an approved managed deployment.
702
730
 
703
- For routines using the executable, supply a JSON array of refs from a file or
704
- standard input. The command emits the captured JSON:
705
-
706
- ```sh
707
- os records read --workspace <workspace> --repository general --refs-file refs.json --at-commit <sha> --json
708
- ```
709
-
710
- Use `--refs-stdin` instead of `--refs-file` for piped JSON. Input is bounded to
711
- 1 MiB and 10,000 distinct refs; captured output is bounded to 25 MiB.
712
-
713
731
  Add an exact file before putting it on an ask or digest. Signed-in members and
714
732
  routines use `inbox.files.add({ path })` within the configured working root:
715
733