sailfork 0.3.0 → 0.3.1

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.
@@ -2,4 +2,4 @@ export * from "./api.js";
2
2
  export { type OpId, ops } from "./ops.js";
3
3
  export * as tools from "./tools.js";
4
4
  export type * as types from "./types.js";
5
- export type { AffectedMode, AffectedStep, AgentTrackingState, Annotation, ApiError, Artifacts, AskKind, AskOptionInput, AutoMerge, BatchItem, BranchUpdated, CaissonAffected, CaissonAsk, CaissonAstMatch, CaissonAstMatches, CaissonBase, CaissonBashResult, CaissonBatchResult, CaissonChange, CaissonChangeRequest, CaissonChanged, CaissonCommitted, CaissonEdit, CaissonFileRead, CaissonFilesRead, CaissonGlob, CaissonGrep, CaissonGrepCount, CaissonGrepLine, CaissonGrepMatch, CaissonLocated, CaissonLspAnswer, CaissonLspPlace, CaissonLspProgress, CaissonLspQuestion, CaissonLspRenamed, CaissonLspStopped, CaissonPage, CaissonPolicy, CaissonPull, CaissonRefused, CaissonReview, CaissonReviewStatus, CaissonRow, CaissonShipped, CaissonTested, Check, CheckRun, CheckRunAction, CheckRunApp, CheckRunApp2, CheckRunBody, CheckRunBrief, CheckRunList, CheckRunOutput, CheckRunText, CheckSource, CheckState, CheckStep, ChecksState, Claim, CloneDefaults, CloneDefaultsEdit, CloseReason, CodeLine, CodeSnippet, CommentKind, CommentProof, ConflictFile, ConflictKind, ConflictResolution, ConflictSide, ConflictTake, ContextVisibility, CreatedIssue, Delegate, DelegateAsk, DelegateRequest, DeletionScheduled, DiffSide, ErrorCode, ErrorLocation, Event, EventPage, EventSubscription, FailedStep, FileHit, FindingResolution, GithubInstallUrl, GithubInstallation, GithubRepo, GrepMode, Held, HeldDecided, HeldListing, HeldRequest, Hidden, HideReason, Inbox, InboxCounts, InboxItem, Issue, IssueAsk, IssueAskAnswer, IssueAskOption, IssueComment, IssueContext, IssueDetail, IssueEvent, IssuePage, IssuePriority, IssueStage, IssueStarted, IssueState, IssueStatus, ItemRef, KeyProof, Label, LabelItem, LabelList, MeUpdated, MergeMethod, Mergeable, Milestone, MilestoneItem, MilestoneList, MilestoneState, MyIssue, MyIssues, NoContent, Opener, PathHit, PathRule, Proof, ProofSource, Pull, PullChecks, PullComment, PullCommit, PullConflicts, PullDetail, PullFile, PullHunk, PullLine, PullMerge, PullPage, PullPatchState, PullThread, QueueBatch, QueueDropped, QueueEntry, QueueStatus, Reaction, Reaction2, ReactionKind, RecoveryCodeList, RefHit, RefHit2, RefResults, RefResults2, RelatedItem, RelatedKind, RelatedLink, RelatedWork, RepoHit, RepoInfo, RepoNote, RepoNoteLimits, RepoNotes, ReviewChange, ReviewComment, ReviewFinding, ReviewFindingInput, ReviewPacket, ReviewRisk, ReviewSince, ReviewSinceFinding, Rollup, Run, RunArtifact, RunCancelled, RunEvent, RunFailures, RunId, RunJob, RunLogPage, RunLogs, RunStep, RunStepLog, RunTests, RunWait, Runs, Sandbox, SandboxBackground, SandboxCaisson, SandboxClass, SandboxExecResult, SandboxHostRef, SandboxIdle, SandboxKind, SandboxOrigin, SandboxPage, SandboxTokenMode, SandboxUsage, SandboxWait, SearchResults, SessionStep, SimilarIssue, SimilarIssues, SkippedWorkflow, SshKey, StackEntry, StopMode, SubIssue, Surface, SymbolHit, SymbolHit2, SymbolResults, SymbolResults2, TestFailure, Token, TokenCreated, TotpSetup, Verdict, Visibility, WaitAnswer, WaitTarget, WorkspaceUnread } from "./types.js";
5
+ export type { AffectedMode, AffectedStep, AgentTrackingState, Annotation, ApiError, Artifacts, AskKind, AskOptionInput, AutoMerge, BatchItem, BranchUpdated, CaissonAffected, CaissonAsk, CaissonAstMatch, CaissonAstMatches, CaissonBase, CaissonBashResult, CaissonBatchResult, CaissonChange, CaissonChangeRequest, CaissonChanged, CaissonCommitted, CaissonEdit, CaissonFileRead, CaissonFilesRead, CaissonGlob, CaissonGrep, CaissonGrepCount, CaissonGrepLine, CaissonGrepMatch, CaissonLocated, CaissonLspAnswer, CaissonLspPlace, CaissonLspProgress, CaissonLspQuestion, CaissonLspRenamed, CaissonLspStopped, CaissonPage, CaissonPolicy, CaissonPull, CaissonRefused, CaissonReview, CaissonReviewStatus, CaissonRow, CaissonShipped, CaissonTested, Check, CheckRun, CheckRunAction, CheckRunApp, CheckRunApp2, CheckRunBody, CheckRunBrief, CheckRunList, CheckRunOutput, CheckRunText, CheckSource, CheckState, CheckStep, ChecksState, Claim, CloneDefaults, CloneDefaultsEdit, CloseReason, CodeLine, CodeSnippet, CommentKind, CommentProof, ConflictFile, ConflictKind, ConflictResolution, ConflictSide, ConflictTake, ContextVisibility, CreatedIssue, Delegate, DelegateAsk, DelegateRequest, DeletionScheduled, DiffSide, EnvChain, EnvChainEntry, EnvDeviceRequest, EnvFile, EnvFileWrite, EnvFiles, EnvLog, EnvLogEntry, EnvPendingRemoval, EnvPerson, EnvRekeyFile, EnvRepo, EnvSigned, ErrorCode, ErrorLocation, Event, EventPage, EventSubscription, FailedStep, FileHit, FindingResolution, GithubInstallUrl, GithubInstallation, GithubRepo, GrepMode, Held, HeldDecided, HeldListing, HeldRequest, Hidden, HideReason, Inbox, InboxCounts, InboxItem, Issue, IssueAsk, IssueAskAnswer, IssueAskOption, IssueComment, IssueContext, IssueDetail, IssueEvent, IssuePage, IssuePriority, IssueStage, IssueStarted, IssueState, IssueStatus, ItemRef, KeyProof, Label, LabelItem, LabelList, MeUpdated, MergeMethod, Mergeable, Milestone, MilestoneItem, MilestoneList, MilestoneState, MyIssue, MyIssues, NoContent, Opener, PathHit, PathRule, Proof, ProofSource, Pull, PullChecks, PullComment, PullCommit, PullConflicts, PullDetail, PullFile, PullHunk, PullLine, PullMerge, PullPage, PullPatchState, PullThread, QueueBatch, QueueDropped, QueueEntry, QueueStatus, Reaction, Reaction2, ReactionKind, RecoveryCodeList, RefHit, RefHit2, RefResults, RefResults2, RelatedItem, RelatedKind, RelatedLink, RelatedWork, RepoHit, RepoInfo, RepoNote, RepoNoteLimits, RepoNotes, ReviewChange, ReviewComment, ReviewFinding, ReviewFindingInput, ReviewPacket, ReviewRisk, ReviewSince, ReviewSinceFinding, Rollup, Run, RunArtifact, RunCancelled, RunEvent, RunFailures, RunId, RunJob, RunLogPage, RunLogs, RunStep, RunStepLog, RunTests, RunWait, Runs, Sandbox, SandboxBackground, SandboxCaisson, SandboxClass, SandboxExecResult, SandboxHostRef, SandboxIdle, SandboxKind, SandboxOrigin, SandboxPage, SandboxTokenMode, SandboxUsage, SandboxWait, SearchResults, SessionStep, SimilarIssue, SimilarIssues, SkippedWorkflow, SshKey, StackEntry, StopMode, SubIssue, Surface, SymbolHit, SymbolHit2, SymbolResults, SymbolResults2, TestFailure, Token, TokenCreated, TotpSetup, Verdict, Visibility, WaitAnswer, WaitTarget, WorkspaceUnread } from "./types.js";
@@ -571,6 +571,110 @@ export declare const ops: {
571
571
  long: false;
572
572
  paginated: false;
573
573
  };
574
+ 'env.chain': {
575
+ id: string;
576
+ method: 'GET';
577
+ path: string;
578
+ pathParams: string[];
579
+ queryParams: string[];
580
+ bodyParams: never[];
581
+ effect: 'read';
582
+ retry: 'safe';
583
+ held: false;
584
+ long: false;
585
+ paginated: false;
586
+ };
587
+ 'env.chain.append': {
588
+ id: string;
589
+ method: 'POST';
590
+ path: string;
591
+ pathParams: string[];
592
+ queryParams: never[];
593
+ bodyParams: string[];
594
+ effect: 'write';
595
+ retry: 'none';
596
+ held: false;
597
+ long: false;
598
+ paginated: false;
599
+ };
600
+ 'env.devices.cancel': {
601
+ id: string;
602
+ method: 'DELETE';
603
+ path: string;
604
+ pathParams: string[];
605
+ queryParams: never[];
606
+ bodyParams: never[];
607
+ effect: 'delete';
608
+ retry: 'idempotent';
609
+ held: false;
610
+ long: false;
611
+ paginated: false;
612
+ };
613
+ 'env.devices.request': {
614
+ id: string;
615
+ method: 'POST';
616
+ path: string;
617
+ pathParams: string[];
618
+ queryParams: never[];
619
+ bodyParams: string[];
620
+ effect: 'write';
621
+ retry: 'none';
622
+ held: false;
623
+ long: false;
624
+ paginated: false;
625
+ };
626
+ 'env.list': {
627
+ id: string;
628
+ method: 'GET';
629
+ path: string;
630
+ pathParams: string[];
631
+ queryParams: string[];
632
+ bodyParams: never[];
633
+ effect: 'read';
634
+ retry: 'safe';
635
+ held: false;
636
+ long: false;
637
+ paginated: false;
638
+ };
639
+ 'env.log': {
640
+ id: string;
641
+ method: 'GET';
642
+ path: string;
643
+ pathParams: string[];
644
+ queryParams: string[];
645
+ bodyParams: never[];
646
+ effect: 'read';
647
+ retry: 'safe';
648
+ held: false;
649
+ long: false;
650
+ paginated: false;
651
+ };
652
+ 'env.version': {
653
+ id: string;
654
+ method: 'GET';
655
+ path: string;
656
+ pathParams: string[];
657
+ queryParams: string[];
658
+ bodyParams: never[];
659
+ effect: 'read';
660
+ retry: 'safe';
661
+ held: false;
662
+ long: false;
663
+ paginated: false;
664
+ };
665
+ 'env.write': {
666
+ id: string;
667
+ method: 'POST';
668
+ path: string;
669
+ pathParams: string[];
670
+ queryParams: never[];
671
+ bodyParams: string[];
672
+ effect: 'write';
673
+ retry: 'none';
674
+ held: false;
675
+ long: false;
676
+ paginated: false;
677
+ };
574
678
  'event_subscriptions.advance': {
575
679
  id: string;
576
680
  method: 'POST';
@@ -659,6 +659,116 @@ export type DeletionScheduled = {
659
659
  deletionAt: string;
660
660
  };
661
661
  export type DiffSide = 'old' | 'new';
662
+ export type EnvChain = {
663
+ /** Whether the caller may append entries: an org owner, or the owner of a personal repository. */
664
+ admin: boolean;
665
+ /** Entries after the requested epoch, oldest first. */
666
+ entries: EnvChainEntry[];
667
+ /** The org's id, or the user's for a personal repository. */
668
+ ownerId: string;
669
+ pendingRemovals: EnvPendingRemoval[];
670
+ /** Handles of the people the chain head names. */
671
+ people: EnvPerson[];
672
+ /** `owner/name` of each repository the chain head grants, so a device can re-encrypt them. */
673
+ repos: EnvRepo[];
674
+ /** Devices waiting for approval: every request for an admin, the caller's own otherwise. */
675
+ requests: EnvDeviceRequest[];
676
+ /** The caller's user id, which their device entries name. */
677
+ userId: string;
678
+ };
679
+ export type EnvChainEntry = {
680
+ body: string;
681
+ createdAt: string;
682
+ epoch: number;
683
+ sig: string;
684
+ };
685
+ /** A device asking to join an owner's env device chain; an admin device approves it by signing a new entry. */
686
+ export type EnvDeviceRequest = {
687
+ /** age X25519 recipient. */
688
+ ageRecipient: string;
689
+ createdAt: string;
690
+ id: number;
691
+ name: string;
692
+ /** Base64 Ed25519 public key. */
693
+ signKey: string;
694
+ user?: string | null;
695
+ userId: string;
696
+ };
697
+ /** The current version of one env file. The manifest and its signature let a device check it without trusting the server; the ciphertext is age, readable only by the devices the chain grants. */
698
+ export type EnvFile = {
699
+ /** Base64 age ciphertext, when asked for. */
700
+ ciphertext?: string | null;
701
+ deleted: boolean;
702
+ epoch: number;
703
+ /** Key names, never values. */
704
+ keys: string[];
705
+ manifest: string;
706
+ path: string;
707
+ sig: string;
708
+ updatedAt: string;
709
+ updatedBy?: string | null;
710
+ version: number;
711
+ };
712
+ /** A new version of one env file: its signed manifest and its age ciphertext (empty for a deletion). */
713
+ export type EnvFileWrite = {
714
+ /** Base64 age ciphertext. */
715
+ ciphertext: string;
716
+ manifest: string;
717
+ path: string;
718
+ sig: string;
719
+ };
720
+ export type EnvFiles = {
721
+ /** The owner's chain epoch; 0 before `sf env init`. */
722
+ epoch: number;
723
+ files: EnvFile[];
724
+ ownerId: string;
725
+ repoId: string;
726
+ };
727
+ export type EnvLog = {
728
+ path: string;
729
+ /** Newest first; the server keeps the newest 100. */
730
+ versions: EnvLogEntry[];
731
+ };
732
+ export type EnvLogEntry = {
733
+ author?: string | null;
734
+ createdAt: string;
735
+ deleted: boolean;
736
+ epoch: number;
737
+ keys: string[];
738
+ message?: string | null;
739
+ version: number;
740
+ };
741
+ /** Someone the chain head still encrypts to who has lost access: a granted user without write access to the repo, or (no `repo`) an admin device whose user is no longer an owner. An admin device's next chain entry removes them. */
742
+ export type EnvPendingRemoval = {
743
+ repo?: string | null;
744
+ repoName?: string | null;
745
+ user?: string | null;
746
+ userId: string;
747
+ };
748
+ export type EnvPerson = {
749
+ handle: string;
750
+ id: string;
751
+ };
752
+ /** An [`EnvFileWrite`] of any of the owner's repositories, re-encrypted alongside a chain entry. */
753
+ export type EnvRekeyFile = {
754
+ ciphertext: string;
755
+ manifest: string;
756
+ path: string;
757
+ /** The repository's id. */
758
+ repo: string;
759
+ sig: string;
760
+ };
761
+ export type EnvRepo = {
762
+ id: string;
763
+ /** `owner/name`. */
764
+ slug: string;
765
+ };
766
+ /** A JSON body and a device's Ed25519 signature over its exact bytes (end-to-end encrypted env files). */
767
+ export type EnvSigned = {
768
+ body: string;
769
+ /** Base64 Ed25519 signature. */
770
+ sig: string;
771
+ };
662
772
  /** The stable machine-readable code of an error. `status` and `hint` for each are in `x-sailfork-codes`. */
663
773
  export type ErrorCode = 'invalid_request' | 'unauthenticated' | 'invalid_token' | 'insufficient_scope' | 'forbidden' | 'not_found' | 'conflict' | 'file_changed' | 'idempotency_in_progress' | 'precondition_failed' | 'payload_too_large' | 'unsupported_media_type' | 'rate_limited' | 'internal' | 'unavailable' | 'busy' | 'agent_policy' | 'agent_change_cap' | 'held_declined' | 'bypass_needs_person' | 'suspended' | 'blocked' | 'private_fork_stays_private' | 'private_forks_off' | 'private_fork_outside_org' | 'sso_deactivated' | 'sso_invite' | 'sso_name_taken' | 'sso_account_linked' | 'sso_expired' | 'disabled' | 'region_blocked';
664
774
  /** Where an error in a step's log points. */
@@ -2862,6 +2972,110 @@ export type CiStepLogInput = {
2862
2972
  repo: string;
2863
2973
  };
2864
2974
  export type CiStepLogOutput = RunLogPage;
2975
+ /**
2976
+ * The owner's env device chain after an epoch, the device requests the caller may see, and the people the head still encrypts to who have lost access. Needs write access to the repository.
2977
+ */
2978
+ export type EnvChainInput = {
2979
+ /** The repository's owner: a user or an org handle. */
2980
+ owner: string;
2981
+ /** The repository's name. */
2982
+ repo: string;
2983
+ /** Only entries after this epoch; 0 or absent for the whole chain. */
2984
+ since?: number | null;
2985
+ };
2986
+ export type EnvChainOutput = EnvChain;
2987
+ /**
2988
+ * Append an entry, signed by an admin device of the head, to the owner's env device chain, with every file it re-encrypts in the same transaction. Org owners only (the owner, for a personal repository).
2989
+ */
2990
+ export type EnvChainAppendInput = {
2991
+ /** The new chain entry and its signature. */
2992
+ entry: EnvSigned;
2993
+ /** Files of the owner's repositories re-encrypted to the new entry's recipients. */
2994
+ files?: EnvRekeyFile[];
2995
+ /** The repository's owner: a user or an org handle. */
2996
+ owner: string;
2997
+ /** The repository's name. */
2998
+ repo: string;
2999
+ };
3000
+ export type EnvChainAppendOutput = EnvChain;
3001
+ /**
3002
+ * Withdraw a device request: the requester's own, or any for an admin.
3003
+ */
3004
+ export type EnvDevicesCancelInput = {
3005
+ /** Request id from `env.chain`. */
3006
+ id: number;
3007
+ /** The repository's owner: a user or an org handle. */
3008
+ owner: string;
3009
+ /** The repository's name. */
3010
+ repo: string;
3011
+ };
3012
+ export type EnvDevicesCancelOutput = null;
3013
+ /**
3014
+ * Ask to add this device to the owner's env device chain; an admin device approves it after comparing the approval code both show. Needs write access to the repository.
3015
+ */
3016
+ export type EnvDevicesRequestInput = {
3017
+ /** age X25519 recipient, `age1...`. */
3018
+ ageRecipient: string;
3019
+ /** A name for the device, such as the machine's host name. */
3020
+ name: string;
3021
+ /** The repository's owner: a user or an org handle. */
3022
+ owner: string;
3023
+ /** The repository's name. */
3024
+ repo: string;
3025
+ /** Base64 Ed25519 public key. */
3026
+ signKey: string;
3027
+ };
3028
+ export type EnvDevicesRequestOutput = EnvDeviceRequest;
3029
+ /**
3030
+ * The repository's env files at their current versions: key names, signed manifests and, with `content`, the age ciphertext. Needs write access to the repository.
3031
+ */
3032
+ export type EnvListInput = {
3033
+ /** true adds each file's ciphertext, so one call pulls everything. */
3034
+ content?: boolean | null;
3035
+ /** The repository's owner: a user or an org handle. */
3036
+ owner: string;
3037
+ /** The repository's name. */
3038
+ repo: string;
3039
+ };
3040
+ export type EnvListOutput = EnvFiles;
3041
+ /**
3042
+ * An env file's versions, newest first: key names, epoch, author and message, never content. Needs write access.
3043
+ */
3044
+ export type EnvLogInput = {
3045
+ /** The repository's owner: a user or an org handle. */
3046
+ owner: string;
3047
+ /** The file's repo-relative path. */
3048
+ path: string;
3049
+ /** The repository's name. */
3050
+ repo: string;
3051
+ };
3052
+ export type EnvLogOutput = EnvLog;
3053
+ /**
3054
+ * One version of one env file with its ciphertext, such as the base of a merge. Needs write access.
3055
+ */
3056
+ export type EnvVersionInput = {
3057
+ /** The repository's owner: a user or an org handle. */
3058
+ owner: string;
3059
+ /** The file's repo-relative path. */
3060
+ path: string;
3061
+ /** The repository's name. */
3062
+ repo: string;
3063
+ version: number;
3064
+ };
3065
+ export type EnvVersionOutput = EnvFile;
3066
+ /**
3067
+ * Store new versions of env files, all or none: each a manifest signed by a device the chain head grants, built on the file's current version, and its age ciphertext. A stale version or chain epoch answers 409. Needs write access.
3068
+ */
3069
+ export type EnvWriteInput = {
3070
+ files: EnvFileWrite[];
3071
+ /** A note for the history, like a commit message. */
3072
+ message?: string | null;
3073
+ /** The repository's owner: a user or an org handle. */
3074
+ owner: string;
3075
+ /** The repository's name. */
3076
+ repo: string;
3077
+ };
3078
+ export type EnvWriteOutput = EnvFiles;
2865
3079
  /**
2866
3080
  * Move a subscription's cursor forward to an event id the reader has finished with. It never moves back: a cursor at or behind the stored one leaves it as it is, so two readers cannot rewind each other.
2867
3081
  */
package/llms.txt CHANGED
@@ -60,6 +60,17 @@
60
60
  - `sf.ci.runs(input)`: List a repository's CI runs, newest first.
61
61
  - `sf.ci.stepLog(input)`: Show one step's log from line `after`, for reading on as the step runs.
62
62
 
63
+ ## env
64
+
65
+ - `sf.env.chain(input)`: The owner's env device chain after an epoch, the device requests the caller may see, and the people the head still encrypts to who have lost access. Needs write access to the repository.
66
+ - `sf.env.chainAppend(input)`: Append an entry, signed by an admin device of the head, to the owner's env device chain, with every file it re-encrypts in the same transaction. Org owners only (the owner, for a personal repository).
67
+ - `sf.env.devicesCancel(input)`: Withdraw a device request: the requester's own, or any for an admin.
68
+ - `sf.env.devicesRequest(input)`: Ask to add this device to the owner's env device chain; an admin device approves it after comparing the approval code both show. Needs write access to the repository.
69
+ - `sf.env.list(input)`: The repository's env files at their current versions: key names, signed manifests and, with `content`, the age ciphertext. Needs write access to the repository.
70
+ - `sf.env.log(input)`: An env file's versions, newest first: key names, epoch, author and message, never content. Needs write access.
71
+ - `sf.env.version(input)`: One version of one env file with its ciphertext, such as the base of a merge. Needs write access.
72
+ - `sf.env.write(input)`: Store new versions of env files, all or none: each a manifest signed by a device the chain head grants, built on the file's current version, and its age ciphertext. A stale version or chain epoch answers 409. Needs write access.
73
+
63
74
  ## event_subscriptions
64
75
 
65
76
  - `sf.event_subscriptions.advance(input)`: Move a subscription's cursor forward to an event id the reader has finished with. It never moves back: a cursor at or behind the stored one leaves it as it is, so two readers cannot rewind each other.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sailfork",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "The Sailfork SDK for TypeScript: issues, pull requests, caissons and CI for agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",