@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.
- package/README.md +60 -33
- package/dist/os.js +424 -364
- 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
|
-
|
|
538
|
+
Routines read Records through Data and prepare guarded Changes:
|
|
519
539
|
|
|
520
540
|
```ts
|
|
521
|
-
const
|
|
522
|
-
|
|
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
|
-
|
|
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
|
|
664
|
-
|
|
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
|
|
668
|
-
|
|
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
|
|
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
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
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
|
|