@oddington/cli 0.1.61 → 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 +60 -33
  2. package/dist/os.js +424 -364
  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,
@@ -599,7 +633,14 @@ provider connections retain their normal network and authority requirements;
599
633
  local execution may contact OS or providers.
600
634
 
601
635
  For modern local execution, install the workspace separately with Bun 1.3.14.
602
- Keep an exact stable `@oddington/sdk` 0.1.x patch through 0.1.33 in root
636
+ For a failed local Run, the terminal and JSON result identify its failed step
637
+ and known SDK error. Device-local `~/.os/<workspace>/runs/<run-id>/execution.json`
638
+ retains redacted exception messages, stacks, causes and failed OS operations.
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
641
+ into a customer routine or an earlier saved Run.
642
+
643
+ Keep an exact stable `@oddington/sdk` 0.1.x patch through 0.1.35 in root
603
644
  `devDependencies`, with its declaration, lock and installed package agreeing.
604
645
  Use compatible Node, the selected private ESM manifest and the shared frozen
605
646
  lock. OS verifies only the selected installed graph, stages its confined bytes
@@ -660,12 +701,14 @@ returns their captured identities in `deleted`, and advances subsequent run
660
701
  reads to the exact prepared version. Files and durable Source uses remain
661
702
  retained. Deleted paths are sealed as absent: recreating one before
662
703
  `os routine publish <run>` invalidates publication before effects.
663
- Later publication rechecks the complete group at its captured base, applies one
664
- exact commit and waits for its exact hosted index. Interrupted Git or index
704
+ Later publication sends the retained group once to the guarded writer, which
705
+ validates its captured intent against the current authoritative head, applies
706
+ one ordinary commit and waits for its exact hosted index. Interrupted Git or index
665
707
  acknowledgements resume that same proposal and preserve the inspected identities.
666
708
 
667
- Publication applies exact Record history when present, retains Files, then
668
- publishes Asks in authored order followed by Digests. Each owning operation
709
+ Publication admits the member, workspace and Run once, uploads referenced or
710
+ explicitly retained local Files with their original IDs, applies Record changes
711
+ when present, then publishes Asks in authored order followed by Digests. Each owning operation
669
712
  validates its own work; a later failure preserves earlier confirmed effects.
670
713
  A Run without Record changes performs no Git freshness/checkout or Data gate.
671
714
  Publication preserves unrelated local work. Changed prepared bytes, authority
@@ -673,34 +716,18 @@ or conflicting Record history require repair and a new Run; publication never
673
716
  rebases inspected work.
674
717
  After interruption, repeat the same publish command with unchanged content.
675
718
  `publication.json` journals attempted operations and confirmed receipts
676
- separately from sealed intent. Fresh launches recover original commit, file and
677
- item identities. A published run reports its stored results. A killed owner
719
+ separately from sealed intent. Fresh launches resume only unconfirmed work using the original operation, File
720
+ and item identities. Confirmed receipts need no second owning-capability call. A published run reports its stored results. A killed owner
678
721
  leaves `preparing.lock`; inspect its recorded PID and root before removing a
679
722
  stale lock, and never remove a live owner's lock.
680
723
 
681
- Installed write grants authorize guarded preparation through
682
- `inbox.repository.updateRecords`. Routines and managed response handlers that
683
- create records use
684
- `inbox.repository.writeRecords`; one request
685
- may combine schema-validated creations with guarded updates and returns the same
686
- authoritative repository receipt. Routine calls supply their stable request
687
- key; a response handler uses its durable execution identity instead.
688
- `inbox.repository.deleteRecords` accepts only
689
- reviewed refs and versions; it atomically refuses stale records and links from
690
- outside the deletion batch.
691
- 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.
692
729
  Customer executable handlers still require an approved managed deployment.
693
730
 
694
- For routines using the executable, supply a JSON array of refs from a file or
695
- standard input. The command emits the captured JSON:
696
-
697
- ```sh
698
- os records read --workspace <workspace> --repository general --refs-file refs.json --at-commit <sha> --json
699
- ```
700
-
701
- Use `--refs-stdin` instead of `--refs-file` for piped JSON. Input is bounded to
702
- 1 MiB and 10,000 distinct refs; captured output is bounded to 25 MiB.
703
-
704
731
  Add an exact file before putting it on an ask or digest. Signed-in members and
705
732
  routines use `inbox.files.add({ path })` within the configured working root:
706
733