@scarn/sdk 0.8.15 → 0.8.18

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 (82) hide show
  1. package/dist/automations/index.js +4 -4
  2. package/dist/{chunk-4ggr8af6.js → chunk-098740f7.js} +1 -1
  3. package/dist/{chunk-1yb2h6t9.js → chunk-0c60x3v8.js} +53 -61
  4. package/dist/{chunk-y2pv8d6a.js → chunk-19brnwkp.js} +1 -1
  5. package/dist/{chunk-b8hxjwag.js → chunk-2tmrw253.js} +2 -2
  6. package/dist/{chunk-z25n32z0.js → chunk-3zp2qtf8.js} +88 -9
  7. package/dist/{chunk-k4y5qt4y.js → chunk-46wmsgv7.js} +1 -1
  8. package/dist/{chunk-ar6hcj1r.js → chunk-6tra3gw8.js} +7 -1
  9. package/dist/{chunk-zf4gwg0p.js → chunk-833ef6dg.js} +170 -269
  10. package/dist/{chunk-11hbmexe.js → chunk-9we3vqsv.js} +1 -1
  11. package/dist/{chunk-5zsavw98.js → chunk-aemxz9r7.js} +19 -3
  12. package/dist/{chunk-43y7tfn4.js → chunk-aknfw08j.js} +1 -1
  13. package/dist/chunk-e0pt5x0e.js +167 -0
  14. package/dist/{chunk-cnxaagfj.js → chunk-evb3hw48.js} +1 -1
  15. package/dist/chunk-mmy80pec.js +64 -0
  16. package/dist/chunk-mzj1j0p5.js +116 -0
  17. package/dist/{chunk-76d1bwwz.js → chunk-p1fs73bd.js} +2 -2
  18. package/dist/{chunk-e1h021kq.js → chunk-pqtd0hr7.js} +13 -3
  19. package/dist/chunk-qgkx89eg.js +210 -0
  20. package/dist/chunk-rphfy0fj.js +167 -0
  21. package/dist/chunk-t1dq2c2s.js +224 -0
  22. package/dist/{chunk-7bpy3w3z.js → chunk-tvjcfh6s.js} +5 -1
  23. package/dist/{chunk-63f90zky.js → chunk-y34zsgsw.js} +1 -1
  24. package/dist/{chunk-skzxcba3.js → chunk-yf15kdte.js} +7087 -1944
  25. package/dist/{chunk-efs789y2.js → chunk-ymywp5ht.js} +2 -2
  26. package/dist/client.js +8 -2
  27. package/dist/connectors/catalog.d.ts +49 -0
  28. package/dist/connectors/index.d.ts +45 -0
  29. package/dist/connectors/index.js +41 -0
  30. package/dist/contracts/artifacts.js +2 -2
  31. package/dist/contracts/automation-document/index.js +3 -3
  32. package/dist/contracts/pipeline-document/index.js +2 -2
  33. package/dist/contracts/step-artifact-submissions.js +2 -2
  34. package/dist/contracts/work-item-changes.js +1 -1
  35. package/dist/defaults/index.js +2 -2
  36. package/dist/definitions/automations/index.js +3 -3
  37. package/dist/definitions/environments/define-environment.d.ts +39 -0
  38. package/dist/definitions/environments/environments-client.d.ts +50 -0
  39. package/dist/definitions/environments/index.d.ts +6 -0
  40. package/dist/definitions/environments/index.js +97 -0
  41. package/dist/definitions/pipelines/index.js +3 -3
  42. package/dist/definitions/steps/compile-mcps.d.ts +8 -12
  43. package/dist/definitions/steps/define-code-step.d.ts +18 -11
  44. package/dist/definitions/steps/define-step.d.ts +14 -25
  45. package/dist/definitions/steps/env.d.ts +30 -8
  46. package/dist/definitions/steps/index.js +35 -18
  47. package/dist/definitions/steps/mcp-server-config.d.ts +19 -9
  48. package/dist/definitions/steps/repo.d.ts +56 -28
  49. package/dist/definitions/steps/runtime.d.ts +54 -39
  50. package/dist/definitions/steps/step-definitions-client.d.ts +222 -63
  51. package/dist/definitions/steps/step-handle.d.ts +8 -1
  52. package/dist/definitions/validation/index.js +10 -7
  53. package/dist/definitions/validation/validate-repo.d.ts +3 -7
  54. package/dist/definitions/validation/validate-runtime.d.ts +2 -7
  55. package/dist/devcontainer-config-path.js +2 -2
  56. package/dist/env-vars.d.ts +57 -1
  57. package/dist/env-vars.js +8 -2
  58. package/dist/environment.d.ts +564 -0
  59. package/dist/environment.js +46 -0
  60. package/dist/generated/index.d.ts +2 -2
  61. package/dist/generated/sdk.gen.d.ts +35 -10
  62. package/dist/generated/types.gen.d.ts +2151 -188
  63. package/dist/health-checks.d.ts +3 -3
  64. package/dist/health-checks.js +2 -2
  65. package/dist/index.d.ts +2 -0
  66. package/dist/index.js +100 -34
  67. package/dist/managed-runtimes.js +2 -2
  68. package/dist/opencode-mcp.d.ts +75 -4
  69. package/dist/opencode-mcp.js +3 -2
  70. package/dist/pipelines/index.js +3 -3
  71. package/dist/push/code-step-lookup.d.ts +6 -0
  72. package/dist/push/code-step-lookup.js +3 -1
  73. package/dist/push/collect-definitions.d.ts +13 -0
  74. package/dist/push/index.js +132 -20
  75. package/dist/push/push-from-directory.d.ts +11 -2
  76. package/dist/repo-config.d.ts +88 -30
  77. package/dist/repo-config.js +22 -6
  78. package/dist/resolve-environment.d.ts +19 -0
  79. package/dist/resolve-environment.js +19 -0
  80. package/dist/task-plane-client.d.ts +139 -22
  81. package/package.json +17 -1
  82. package/dist/chunk-xzx08r6y.js +0 -103
@@ -3,29 +3,30 @@ import type { AnyStepFeature, FeatureResultExtensions, Grant } from "./step-feat
3
3
  import { type PromptTemplateContext } from "./prompt-template";
4
4
  import { type HealthChecksInput, type StepHealthChecksInput } from "../../health-checks";
5
5
  import type { OpenCodeMcpServers } from "../../opencode-mcp";
6
- import type { EnvVarsInput } from "../../env-vars";
7
6
  import type { RepoConfigInput } from "../../repo-config";
8
7
  import type { EnvRecord, PromptEnvContext } from "./env";
9
- import { type StepEnvironment } from "./runtime";
8
+ import { type CompiledEnvironment, type InlineStepEnvironment, type NamedStepEnvironment } from "./runtime";
9
+ import { type RepoField, type RepoSpec } from "./repo";
10
10
  import type { McpHandle } from "./define-mcp";
11
11
  import type { BuiltInError, ConversationResult } from "../../pipelines/types";
12
12
  import { type StepHandle } from "./step-handle";
13
13
  type Prettify<T> = {
14
14
  [K in keyof T]: T[K];
15
15
  } & {};
16
- export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TEnv extends EnvRecord = EnvRecord> = {
16
+ export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TEnv extends EnvRecord = EnvRecord, TNamed extends NamedStepEnvironment | undefined = NamedStepEnvironment | undefined> = {
17
17
  key: string;
18
18
  name: string;
19
19
  description?: string | null;
20
20
  version?: number;
21
21
  /**
22
- * Where the step runs (`runtime`), its environment variables (`vars`) and what
23
- * it may do to the repository (`repo`). Declare it before `agentPrompt` so
24
- * `TEnv` is inferred from `vars` into the prompt's `env`, which is then
25
- * strict: only declared, non-secret keys.
22
+ * A named environment, by name or by `defineEnvironment` handle, or an
23
+ * inline runtime, checkout branch and variables (`vars`). Declare it before
24
+ * `agentPrompt` and a `repo` function so their `env` is typed from the
25
+ * handle's or the inline `vars`: only declared, non-secret keys.
26
26
  */
27
- environment?: StepEnvironment<TInput["_output"], TEnv, TResult["_output"]>;
28
- agentPrompt: string | ((context: PromptTemplateContext<TInput["_output"], PromptEnvContext<TEnv>>) => string);
27
+ environment?: InlineStepEnvironment<TInput["_output"], TEnv> | TNamed;
28
+ repo?: RepoField<TInput["_output"], TResult["_output"], RepoSpec, PromptEnvContext<TEnv, TNamed>>;
29
+ agentPrompt: string | ((context: PromptTemplateContext<TInput["_output"], PromptEnvContext<TEnv, TNamed>>) => string);
29
30
  input?: TInput;
30
31
  result?: TResult;
31
32
  features?: AnyStepFeature[];
@@ -91,21 +92,10 @@ export type StepDefinitionSpec = {
91
92
  version: number;
92
93
  kind: "user_defined" | "code";
93
94
  status: "draft" | "active" | "archived";
94
- executionMode?: "workspace" | "no_workspace";
95
+ environment: CompiledEnvironment;
95
96
  /**
96
- * Repo-relative path of the devcontainer config to launch; `null` or omitted
97
- * means auto-detect. Only valid with `executionMode: "workspace"`.
98
- */
99
- devcontainerConfigPath?: string | null;
100
- /**
101
- * Identifier of the worker-supplied managed runtime (`Runtime.managed.<id>()`);
102
- * `null` or omitted means not managed. Only valid on a `code` step with
103
- * `executionMode: "workspace"` and no `devcontainerConfigPath`.
104
- */
105
- managedRuntime?: string | null;
106
- /**
107
- * Repository access. Omitted means the runtime's default (`readWrite` for
108
- * `workspace`, `none` for `no_workspace`), which the server resolves.
97
+ * Repository access. Omitted means the server resolves the default; shared
98
+ * repo resolution defaults to `readWrite` for every runtime.
109
99
  */
110
100
  repo?: RepoConfigInput;
111
101
  prompt: string | null;
@@ -113,7 +103,6 @@ export type StepDefinitionSpec = {
113
103
  resultSchemaJson: Record<string, unknown> | null;
114
104
  opencodeMcpJson: OpenCodeMcpServers | null;
115
105
  healthChecksJson: HealthChecksInput | null;
116
- envJson?: EnvVarsInput | null;
117
106
  /** Error names the step declares besides the built-in ones. */
118
107
  errors?: readonly string[];
119
108
  /**
@@ -152,7 +141,7 @@ export type EffectiveResult<TResult, TFeatures extends ReadonlyArray<AnyStepFeat
152
141
  * its effective result.
153
142
  */
154
143
  export type DefineStepResult<TResult extends ZodType, TFeatures extends ReadonlyArray<AnyStepFeature>> = ZodType extends TResult ? [keyof FeatureResultExtensions<TFeatures>] extends [never] ? ConversationResult : EffectiveResult<TResult["_output"], TFeatures> : EffectiveResult<TResult["_output"], TFeatures>;
155
- export declare function defineStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<AnyStepFeature> = never[], TEnv extends EnvRecord = EnvRecord, const TErrors extends string = never>(config: Omit<DefineStepInput<TInput, TResult, TEnv>, "features" | "errors" | "retry"> & {
144
+ export declare function defineStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<AnyStepFeature> = never[], TEnv extends EnvRecord = EnvRecord, const TErrors extends string = never, TNamed extends NamedStepEnvironment | undefined = undefined>(config: Omit<DefineStepInput<TInput, TResult, TEnv, TNamed>, "features" | "errors" | "retry"> & {
156
145
  features?: TFeatures;
157
146
  errors?: readonly TErrors[];
158
147
  retry?: readonly {
@@ -58,7 +58,13 @@ export type EnvInherit<TSecret extends boolean = boolean, TOptional extends bool
58
58
  readonly default: TDefault;
59
59
  readonly applies: EnvVarApplies;
60
60
  };
61
- export type EnvEntry = string | EnvValue | EnvInherit;
61
+ /** A project secret saved in Scarn, referenced by name. Always masked. */
62
+ export type EnvSecret = {
63
+ readonly kind: "secret";
64
+ readonly secretName: string;
65
+ readonly applies: EnvVarApplies;
66
+ };
67
+ export type EnvEntry = string | EnvValue | EnvInherit | EnvSecret;
62
68
  export type EnvRecord = Record<string, EnvEntry>;
63
69
  /** Runs once at definition time, against the same input proxy `agentPrompt` uses. */
64
70
  export type EnvFn<TInput, TEnv extends EnvRecord = EnvRecord> = (context: {
@@ -91,12 +97,19 @@ export type PromptEnv<TEnv extends EnvRecord> = {
91
97
  } ? K : never]: PromptEntryValue<TEnv[K]>;
92
98
  };
93
99
  /**
94
- * The prompt `env` type for a step: strict (`PromptEnv`) once
95
- * `environment.vars` is declared, today's loose record otherwise. Undeclared
96
- * `vars` leaves `TEnv` at its `EnvRecord` default, whose index signature is the
97
- * marker.
100
+ * The prompt `env` type for a step: a string record for an environment given
101
+ * by name, strict (`PromptEnv`) for an environment handle or once inline
102
+ * `environment.vars` is declared, and an optional string record otherwise.
103
+ * Undeclared `vars` leaves `TEnv` at its `EnvRecord` default, whose index
104
+ * signature is the marker; a handle typed as plain `EnvironmentHandle` (vars
105
+ * unknown) gets the string record. `TNamed` is the step's named environment,
106
+ * if any.
98
107
  */
99
- export type PromptEnvContext<TEnv extends EnvRecord> = string extends keyof TEnv ? PromptInputProxy<Record<string, string | undefined>> : PromptEnv<TEnv>;
108
+ export type PromptEnvContext<TEnv extends EnvRecord, TNamed extends string | {
109
+ readonly __env: EnvRecord;
110
+ } | undefined = undefined> = [TNamed] extends [string] ? Record<string, string> : [TNamed] extends [{
111
+ readonly __env: infer THandleEnv extends EnvRecord;
112
+ }] ? string extends keyof THandleEnv ? Record<string, string> : PromptEnv<THandleEnv> : string extends keyof TEnv ? PromptInputProxy<Record<string, string | undefined>> : PromptEnv<TEnv>;
100
113
  export declare const Env: {
101
114
  /**
102
115
  * A literal or `{{input.…}}` template value. Same as writing a bare string,
@@ -126,11 +139,20 @@ export declare const Env: {
126
139
  * example to steer the repo's `initializeCommand`.
127
140
  */
128
141
  readonly inherit: <const O extends InheritOpts = Record<never, never>>(opts?: O) => EnvInherit<SecretOf<O>, OptionalOf<O>, DefaultOf<O>>;
142
+ /**
143
+ * Reads a project secret saved in Scarn, looked up by `secretName` at run
144
+ * time (the worker's `.scarn/.env` first, then Scarn; never `process.env`).
145
+ * The variable name comes from the key and may differ from the secret name.
146
+ *
147
+ * - Stored: only the secret's name.
148
+ * - Masked: always. A secret variable has no default.
149
+ */
150
+ readonly secret: (secretName: string, opts?: EnvAppliesOpt) => EnvSecret;
129
151
  };
130
152
  /**
131
- * Runs the authored `environment.vars` function once and returns the wire
153
+ * Evaluates the authored `environment.vars` record or function once and returns the wire
132
154
  * shape, or `null` when the step declares no `vars` (or an empty record).
133
155
  * Throws on a static secret, or a static literal on a secret-looking name.
134
156
  */
135
- export declare function normalizeEnv<TInput>(fn: EnvFn<TInput> | undefined): EnvVarsInput | null;
157
+ export declare function normalizeEnv<TInput>(fn: EnvFn<TInput> | EnvRecord | undefined): EnvVarsInput | null;
136
158
  export {};
@@ -3,22 +3,19 @@ import {
3
3
  ARTIFACT_BRAND,
4
4
  Artifact,
5
5
  ArtifactTypes,
6
- Env,
7
6
  Features,
8
7
  Notify,
9
8
  Repo,
10
- Runtime,
9
+ WorkBranch,
11
10
  artifact,
11
+ assertBaseBranchFitsEnvironment,
12
12
  codeStep,
13
- compileEnvironment,
14
13
  compileMcps,
15
14
  compileRepo,
16
15
  compileStepConcurrency,
17
16
  compileStepErrors,
18
17
  compileStepMaxTurns,
19
18
  compileStepRetry,
20
- createPromptInputProxy,
21
- createPromptTemplateContext,
22
19
  createStepDefinitionsClient,
23
20
  defineMcp,
24
21
  defineStep,
@@ -26,27 +23,41 @@ import {
26
23
  grantActionValues,
27
24
  grantScopeValues,
28
25
  isMcpHandle,
29
- isSecretLookingEnvName,
30
26
  normalizeArtifactAccept,
31
- normalizeEnv,
32
- renderPromptTemplate,
33
27
  resolveMcpChecks,
28
+ stepEnvironmentHandle,
34
29
  toStepHandle,
35
30
  toStepSpec
36
- } from "../../chunk-zf4gwg0p.js";
37
- import"../../chunk-e1h021kq.js";
38
- import"../../chunk-63f90zky.js";
31
+ } from "../../chunk-833ef6dg.js";
32
+ import"../../chunk-y34zsgsw.js";
33
+ import {
34
+ Env,
35
+ Runtime,
36
+ assertNoSetupVarsOnHost,
37
+ compileConnectors,
38
+ compileEnvironment,
39
+ createPromptInputProxy,
40
+ createPromptTemplateContext,
41
+ isSecretLookingEnvName,
42
+ knownEnvironmentVars,
43
+ normalizeEnv,
44
+ renderPromptTemplate
45
+ } from "../../chunk-t1dq2c2s.js";
46
+ import"../../chunk-6tra3gw8.js";
39
47
  import"../../chunk-jj9pezwb.js";
40
48
  import"../../chunk-y11p1q7r.js";
41
- import"../../chunk-5zsavw98.js";
42
- import"../../chunk-4ggr8af6.js";
43
- import"../../chunk-k4y5qt4y.js";
44
- import"../../chunk-xzx08r6y.js";
45
- import"../../chunk-z25n32z0.js";
49
+ import"../../chunk-rphfy0fj.js";
50
+ import"../../chunk-e0pt5x0e.js";
51
+ import"../../chunk-098740f7.js";
52
+ import"../../chunk-46wmsgv7.js";
53
+ import"../../chunk-qgkx89eg.js";
54
+ import"../../chunk-pqtd0hr7.js";
55
+ import"../../chunk-aemxz9r7.js";
56
+ import"../../chunk-3zp2qtf8.js";
46
57
  import"../../chunk-ngy1fdcx.js";
47
- import"../../chunk-y2pv8d6a.js";
58
+ import"../../chunk-19brnwkp.js";
48
59
  import"../../chunk-01nfqm18.js";
49
- import"../../chunk-skzxcba3.js";
60
+ import"../../chunk-yf15kdte.js";
50
61
  import"../../chunk-y64skrwp.js";
51
62
  export {
52
63
  ARTIFACT_BRAND,
@@ -57,8 +68,12 @@ export {
57
68
  Notify,
58
69
  Repo,
59
70
  Runtime,
71
+ WorkBranch,
60
72
  artifact,
73
+ assertBaseBranchFitsEnvironment,
74
+ assertNoSetupVarsOnHost,
61
75
  codeStep,
76
+ compileConnectors,
62
77
  compileEnvironment,
63
78
  compileMcps,
64
79
  compileRepo,
@@ -75,10 +90,12 @@ export {
75
90
  grantScopeValues,
76
91
  isMcpHandle,
77
92
  isSecretLookingEnvName,
93
+ knownEnvironmentVars,
78
94
  normalizeArtifactAccept,
79
95
  normalizeEnv,
80
96
  renderPromptTemplate,
81
97
  resolveMcpChecks,
98
+ stepEnvironmentHandle,
82
99
  toStepHandle,
83
100
  toStepSpec,
84
101
  exports_z as z
@@ -5,12 +5,22 @@ declare const refFieldsSchema: z.ZodObject<{
5
5
  catalog: z.ZodOptional<z.ZodInt>;
6
6
  execution: z.ZodOptional<z.ZodInt>;
7
7
  }, z.core.$strict>>;
8
+ workerVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
9
+ name: z.ZodString;
10
+ source: z.ZodLiteral<"inherit">;
11
+ from: z.ZodString;
12
+ secret: z.ZodBoolean;
13
+ optional: z.ZodBoolean;
14
+ default: z.ZodOptional<z.ZodString>;
15
+ mcp: z.ZodOptional<z.ZodString>;
16
+ applies: z.ZodLiteral<"agent">;
17
+ }, z.core.$strict>>>;
18
+ codemode: z.ZodOptional<z.ZodBoolean>;
8
19
  protocol: z.ZodOptional<z.ZodEnum<{
9
20
  auto: "auto";
10
21
  legacy: "legacy";
11
22
  "2026-07-28": "2026-07-28";
12
23
  }>>;
13
- codemode: z.ZodOptional<z.ZodBoolean>;
14
24
  }, z.core.$strict>;
15
25
  declare const localFieldsSchema: z.ZodObject<{
16
26
  timeout: z.ZodOptional<z.ZodObject<{
@@ -19,14 +29,14 @@ declare const localFieldsSchema: z.ZodObject<{
19
29
  execution: z.ZodOptional<z.ZodInt>;
20
30
  }, z.core.$strict>>;
21
31
  command: z.ZodArray<z.ZodString>;
32
+ cwd: z.ZodOptional<z.ZodString>;
33
+ environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
34
+ codemode: z.ZodOptional<z.ZodBoolean>;
22
35
  protocol: z.ZodOptional<z.ZodEnum<{
23
36
  auto: "auto";
24
37
  legacy: "legacy";
25
38
  "2026-07-28": "2026-07-28";
26
39
  }>>;
27
- cwd: z.ZodOptional<z.ZodString>;
28
- environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
29
- codemode: z.ZodOptional<z.ZodBoolean>;
30
40
  }, z.core.$strict>;
31
41
  declare const remoteFieldsSchema: z.ZodObject<{
32
42
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -36,11 +46,6 @@ declare const remoteFieldsSchema: z.ZodObject<{
36
46
  catalog: z.ZodOptional<z.ZodInt>;
37
47
  execution: z.ZodOptional<z.ZodInt>;
38
48
  }, z.core.$strict>>;
39
- protocol: z.ZodOptional<z.ZodEnum<{
40
- auto: "auto";
41
- legacy: "legacy";
42
- "2026-07-28": "2026-07-28";
43
- }>>;
44
49
  oauth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
45
50
  client_id: z.ZodOptional<z.ZodString>;
46
51
  client_secret: z.ZodOptional<z.ZodString>;
@@ -50,6 +55,11 @@ declare const remoteFieldsSchema: z.ZodObject<{
50
55
  auth_server_metadata_url: z.ZodOptional<z.ZodString>;
51
56
  }, z.core.$strict>, z.ZodLiteral<false>]>>;
52
57
  codemode: z.ZodOptional<z.ZodBoolean>;
58
+ protocol: z.ZodOptional<z.ZodEnum<{
59
+ auto: "auto";
60
+ legacy: "legacy";
61
+ "2026-07-28": "2026-07-28";
62
+ }>>;
53
63
  }, z.core.$strict>;
54
64
  /** The shared OpenCode fields a `ref` applies on top of the repo's definition. */
55
65
  export type McpRefServerFields = z.output<typeof refFieldsSchema>;
@@ -1,15 +1,10 @@
1
- import { type RepoConfigInput, type RepoGitCredentials } from "../../repo-config";
1
+ import { type BaseBranchEnvVar, type RepoConfigInput, type RepoGitCredentials, type RepoWorkBranch } from "../../repo-config";
2
2
  import { type PromptInputProxy } from "./prompt-template";
3
- import type { RuntimeSpec } from "./runtime";
4
3
  /**
5
- * Authoring helpers for a step's `environment.repo` option, and the
4
+ * Authoring helpers for a step's top-level `repo` option, and the
6
5
  * definition-time compilation that turns it into the `repo` wire field
7
6
  * (`../../repo-config.ts`).
8
7
  */
9
- /** The step gets no repository: no clone, branch, commit or push. */
10
- export type NoneRepoSpec = {
11
- readonly mode: "none";
12
- };
13
8
  type GitCredentialsOpt = {
14
9
  /**
15
10
  * Defaults to `"auto"`: git inside the container gets credentials (for
@@ -19,10 +14,21 @@ type GitCredentialsOpt = {
19
14
  */
20
15
  readonly gitCredentials?: RepoGitCredentials;
21
16
  };
17
+ type BranchOpts = {
18
+ /**
19
+ * The branch to start from, a single-line template: `{{input.…}}`,
20
+ * `{{env.NAME}}` (a variable declared in the step's environment) and
21
+ * `{{workItem.platformKey}}` tokens only. Without tokens it must be a valid
22
+ * branch name. When set, it beats the previous step's work branch. Unset,
23
+ * the step starts from the previous step's work branch, else the worker's
24
+ * or project's base branch, else the remote's default branch.
25
+ */
26
+ readonly baseBranch?: string;
27
+ };
22
28
  /** Clones and checks out the base branch; creates no branch, commits and pushes nothing. */
23
29
  export type ReadOnlyRepoSpec = {
24
30
  readonly mode: "readOnly";
25
- } & GitCredentialsOpt;
31
+ } & GitCredentialsOpt & BranchOpts;
26
32
  export type ReadWriteRepoSpec = {
27
33
  readonly mode: "readWrite";
28
34
  /**
@@ -33,33 +39,36 @@ export type ReadWriteRepoSpec = {
33
39
  readonly message?: string;
34
40
  /** Defaults to `"fail"`: a failed push fails the step. */
35
41
  readonly onPushFailure?: "fail" | "warn";
36
- } & GitCredentialsOpt;
37
- export type RepoSpec = NoneRepoSpec | ReadOnlyRepoSpec | ReadWriteRepoSpec;
38
- /** What `Runtime.devcontainer()` and `Runtime.managed.<id>()` accept. */
39
- export type DevcontainerRepoSpec = ReadOnlyRepoSpec | ReadWriteRepoSpec;
40
- /** What `Runtime.host()` accepts. */
41
- export type HostRepoSpec = NoneRepoSpec;
42
- /** Runs once at definition time, against the same proxies `agentPrompt` and `vars` use. */
42
+ /**
43
+ * Defaults to `WorkBranch.create()`, a new `scarn/<key>-<id>` branch.
44
+ * `WorkBranch.base()` commits onto the branch the step started from.
45
+ */
46
+ readonly workBranch?: RepoWorkBranch;
47
+ } & GitCredentialsOpt & BranchOpts;
48
+ export type RepoSpec = ReadOnlyRepoSpec | ReadWriteRepoSpec;
43
49
  /** The work item values a commit message may name, read live at commit time. */
44
50
  export type CommitMessageWorkItem = {
45
51
  title: string;
46
52
  platformKey: string;
47
53
  };
48
- export type RepoFn<TInput, TResult, TSpec extends RepoSpec> = (context: {
54
+ /** The default `env` of a repo function: any variable, as a token. */
55
+ export type RepoEnvDefault = PromptInputProxy<Record<string, string | undefined>>;
56
+ /**
57
+ * Runs once at definition time, against the same proxies `agentPrompt` and
58
+ * `vars` use. `env` is typed as `agentPrompt`'s is (`PromptEnvContext`).
59
+ */
60
+ export type RepoFn<TInput, TResult, TSpec extends RepoSpec, TEnv = RepoEnvDefault> = (context: {
49
61
  input: PromptInputProxy<TInput>;
50
62
  result: PromptInputProxy<TResult>;
51
63
  /** The Task's work item: `{{workItem.title}}` and `{{workItem.platformKey}}`. */
52
64
  workItem: PromptInputProxy<CommitMessageWorkItem>;
65
+ /** The step's environment variables, for `baseBranch`: `{{env.NAME}}`. */
66
+ env: TEnv;
53
67
  }) => TSpec;
54
- export type RepoField<TInput, TResult, TSpec extends RepoSpec> = TSpec | RepoFn<TInput, TResult, TSpec>;
68
+ export type RepoField<TInput, TResult, TSpec extends RepoSpec, TEnv = RepoEnvDefault> = TSpec | RepoFn<TInput, TResult, TSpec, TEnv>;
55
69
  export type ReadOnlyRepoOpts = Omit<ReadOnlyRepoSpec, "mode">;
56
70
  export type ReadWriteRepoOpts = Omit<ReadWriteRepoSpec, "mode">;
57
71
  export declare const Repo: {
58
- /**
59
- * The step gets no repository. What `Runtime.host()` already implies, stated
60
- * as a value. Only valid with `Runtime.host()`.
61
- */
62
- readonly none: () => NoneRepoSpec;
63
72
  /**
64
73
  * Clones and checks out the base branch, but creates no work branch, commits
65
74
  * nothing, pushes nothing and reports no `workBranch`. A policy, not a
@@ -68,19 +77,38 @@ export declare const Repo: {
68
77
  readonly readOnly: (opts?: ReadOnlyRepoOpts) => ReadOnlyRepoSpec;
69
78
  /**
70
79
  * Creates a work branch, then commits and pushes it when the step succeeds.
71
- * This is the default for a devcontainer step.
80
+ * This is the shared default for every runtime.
72
81
  */
73
82
  readonly readWrite: (opts?: ReadWriteRepoOpts) => ReadWriteRepoSpec;
74
83
  };
84
+ /** Which branch a `Repo.readWrite()` step commits to (its `workBranch`). */
85
+ export declare const WorkBranch: {
86
+ /** A new `scarn/<key>-<id>` branch. The default. */
87
+ readonly create: () => RepoWorkBranch;
88
+ /**
89
+ * The branch the step started from: the rendered `baseBranch`, else the
90
+ * previous step's work branch. Pushed without force, so a moved origin fails
91
+ * the push. Needs an explicit `baseBranch`; a worker, project or remote
92
+ * default base is rejected at startup.
93
+ */
94
+ readonly base: () => RepoWorkBranch;
95
+ };
75
96
  export type CompileRepoContext = {
76
97
  /** Named in error messages. */
77
98
  readonly stepKey?: string;
78
99
  };
79
100
  /**
80
- * Runs the authored `environment.repo` once (the function form against `input`
81
- * and `result` proxies) and returns the wire shape, or `undefined` when the step
82
- * declares no `repo`. Throws when the mode does not fit the runtime or breaks
83
- * the `repoConfigInputSchema` rules.
101
+ * Runs the authored `repo` once (the function form against `input`, `result`,
102
+ * `workItem` and `env` proxies) and returns the wire shape, or `undefined`
103
+ * when the step declares no `repo`. Throws when it breaks the
104
+ * `repoConfigInputSchema` rules, e.g. a `{{result.…}}` token in `baseBranch`.
105
+ */
106
+ export declare function compileRepo<TInput, TResult, TEnv = RepoEnvDefault>(repo: RepoField<TInput, TResult, RepoSpec, TEnv> | undefined, ctx?: CompileRepoContext): RepoConfigInput | undefined;
107
+ /**
108
+ * Throws when the compiled `repo.baseBranch` has an `{{env.X}}` token the
109
+ * step's environment doesn't allow (undeclared, or secret). `vars` is the
110
+ * environment's var list, or `undefined` for an environment known only by
111
+ * name: the server checks that one at publish.
84
112
  */
85
- export declare function compileRepo<TInput, TResult>(repo: RepoField<TInput, TResult, RepoSpec> | undefined, runtime: RuntimeSpec | undefined, ctx?: CompileRepoContext): RepoConfigInput | undefined;
113
+ export declare function assertBaseBranchFitsEnvironment(repo: RepoConfigInput | undefined, vars: readonly BaseBranchEnvVar[] | undefined, ctx?: CompileRepoContext): void;
86
114
  export {};
@@ -1,12 +1,11 @@
1
1
  import type { EnvVarsInput } from "../../env-vars";
2
2
  import { type ManagedRuntimeId } from "../../managed-runtimes";
3
- import type { RepoConfigInput } from "../../repo-config";
4
3
  import { type EnvFn, type EnvRecord } from "./env";
5
- import { type CompileRepoContext, type DevcontainerRepoSpec, type HostRepoSpec, type RepoField } from "./repo";
4
+ import type { CompileRepoContext } from "./repo";
5
+ import type { EnvironmentHandle } from "../environments/define-environment";
6
6
  /**
7
7
  * Authoring helpers for a step's `environment` option, and the definition-time
8
- * compilation that turns it into the wire fields `executionMode`,
9
- * `managedRuntime`, `devcontainerConfigPath`, `envJson` and `repo`.
8
+ * compilation that turns it into a named or inline environment reference.
10
9
  */
11
10
  /** Where a step runs. Build one with `Runtime.devcontainer()`, `Runtime.host()` or `Runtime.managed.<id>()`. */
12
11
  export type DevcontainerRuntimeSpec = {
@@ -26,39 +25,39 @@ export type ManagedRuntimeSpec<TId extends ManagedRuntimeId = ManagedRuntimeId>
26
25
  };
27
26
  export type RuntimeSpec = DevcontainerRuntimeSpec | HostRuntimeSpec | ManagedRuntimeSpec;
28
27
  /**
29
- * How a step runs: its `runtime`, its environment `vars` and its `repo` access.
30
- * A union on the runtime kind, so a `repo` the runtime cannot honor is a type
31
- * error: a host step takes only `Repo.none()`, a devcontainer or managed step
32
- * takes `Repo.readOnly()` or `Repo.readWrite()`.
28
+ * A named environment, by name or by `defineEnvironment` handle, or an inline
29
+ * runtime, vars and connectors.
33
30
  *
34
- * Declare `vars` before `agentPrompt` so `TEnv` is inferred into the prompt's
35
- * `env`, which is then strict: only declared, non-secret keys.
31
+ * For inline environments, declare `vars` before `agentPrompt` so `TEnv` is
32
+ * inferred into the prompt's `env`: only declared, non-secret keys. A handle
33
+ * types the prompt's `env` from its own `vars` the same way.
36
34
  */
37
- export type StepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord, TResult = unknown> = {
38
- /** Defaults to `Runtime.devcontainer()`. */
39
- runtime?: DevcontainerRuntimeSpec | ManagedRuntimeSpec;
40
- vars?: EnvFn<TInput, TEnv>;
41
- /** Defaults to `Repo.readWrite()`. */
42
- repo?: RepoField<TInput, TResult, DevcontainerRepoSpec>;
43
- } | {
44
- runtime: HostRuntimeSpec;
45
- vars?: EnvFn<TInput, TEnv>;
46
- /** Defaults to `Repo.none()`. */
47
- repo?: RepoField<TInput, TResult, HostRepoSpec>;
35
+ export type StepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord> = string | EnvironmentHandle<TEnv> | InlineStepEnvironment<TInput, TEnv>;
36
+ /** A named environment: its name, or its `defineEnvironment` handle. */
37
+ export type NamedStepEnvironment = string | EnvironmentHandle;
38
+ export type InlineStepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord> = {
39
+ /** Defaults to the repository's runtime. */
40
+ runtime?: RuntimeSpec;
41
+ vars?: EnvFn<TInput, TEnv> | TEnv;
42
+ /**
43
+ * Scarn catalog connectors to turn on, e.g. `["datadog"]`. `vars` must
44
+ * provide each connector's required variables.
45
+ */
46
+ connectors?: readonly string[];
48
47
  };
49
48
  /**
50
49
  * `codeStep`'s environment: `StepEnvironment`'s workspace variant. A code step
51
- * runs repo code, which needs a clone, and the host runtime has none.
50
+ * currently requires a devcontainer or managed runtime.
52
51
  */
53
- export type CodeStepEnvironment<TInput, TResult = unknown> = {
52
+ export type CodeStepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord> = NamedStepEnvironment | InlineCodeStepEnvironment<TInput, TEnv>;
53
+ /** `codeStep`'s inline environment. */
54
+ export type InlineCodeStepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord> = {
54
55
  /**
55
56
  * Defaults to `Runtime.managed.bun1()`. `Runtime.devcontainer()` opts into the
56
57
  * project's own container. `Runtime.host()` is not supported.
57
58
  */
58
59
  runtime?: DevcontainerRuntimeSpec | ManagedRuntimeSpec;
59
- vars?: EnvFn<TInput>;
60
- /** Defaults to `Repo.readWrite()`. */
61
- repo?: RepoField<TInput, TResult, DevcontainerRepoSpec>;
60
+ vars?: EnvFn<TInput, TEnv> | TEnv;
62
61
  };
63
62
  export type DevcontainerRuntimeOpts = {
64
63
  /**
@@ -87,28 +86,44 @@ export declare const Runtime: {
87
86
  */
88
87
  readonly devcontainer: (opts?: DevcontainerRuntimeOpts) => DevcontainerRuntimeSpec;
89
88
  /**
90
- * Runs the step on the worker host, with no clone and no container. Takes no
89
+ * Runs the step on the worker host, without a container. Takes no
91
90
  * options, so a config path cannot be combined with it. Not supported for
92
- * `codeStep`, which needs a workspace.
91
+ * `codeStep`, which needs a container.
93
92
  */
94
93
  readonly host: () => HostRuntimeSpec;
95
94
  };
96
- export type CompiledEnvironment = {
97
- executionMode: "workspace" | "no_workspace";
98
- devcontainerConfigPath: string | null;
99
- managedRuntime: ManagedRuntimeId | null;
95
+ export type CompiledInlineEnvironment = {
96
+ kind: "inline";
97
+ runtime?: RuntimeSpec;
100
98
  envJson: EnvVarsInput | null;
101
- /** `undefined` when the author wrote no `repo`; the server resolves the default. */
102
- repo: RepoConfigInput | undefined;
99
+ connectors?: string[];
103
100
  };
101
+ export type CompiledEnvironment = CompiledInlineEnvironment | {
102
+ kind: "named";
103
+ name: string;
104
+ } | null;
104
105
  export type CompileEnvironmentContext = CompileRepoContext & {
105
106
  /** Used when the environment declares no `runtime`. `codeStep` passes the default managed runtime. */
106
107
  readonly defaultRuntime?: ManagedRuntimeSpec;
107
108
  };
108
109
  /**
109
- * Turns the authored `environment` into its wire fields. Runs `vars` and `repo`
110
- * once. Throws on a static secret, or a static literal on a secret-looking name,
111
- * on a setup variable on the host runtime, and on a `repo` the runtime cannot
112
- * honor or that breaks the commit message rules.
110
+ * A host step has no container, so nothing runs `devcontainer up`. `owner`
111
+ * prefixes the error, e.g. `Step "fix-bug"` or `Environment "frontend"`.
112
+ */
113
+ export declare function assertNoSetupVarsOnHost(envJson: EnvVarsInput | null, runtime: RuntimeSpec | undefined, owner: string | undefined): void;
114
+ /** Checks connector ids against the catalog. `owner` prefixes the error. */
115
+ export declare function compileConnectors(connectors: readonly string[] | undefined, owner: string | undefined): string[] | undefined;
116
+ /**
117
+ * The vars a step's environment declares, as definition time knows them: a
118
+ * handle's content vars, or the compiled inline vars (none when the step has
119
+ * no environment). `undefined` for an environment named by string, which the
120
+ * server checks at publish.
121
+ */
122
+ export declare function knownEnvironmentVars<TInput, TEnv extends EnvRecord>(environment: StepEnvironment<TInput, TEnv> | CodeStepEnvironment<TInput> | undefined, compiled: CompiledEnvironment): EnvVarsInput | undefined;
123
+ /**
124
+ * Turns the authored `environment` into a reference. Named environments are
125
+ * resolved by the worker; inline environments run `vars` once and reject static
126
+ * secrets and setup variables on the host runtime.
113
127
  */
114
- export declare function compileEnvironment<TInput, TEnv extends EnvRecord, TResult>(environment: StepEnvironment<TInput, TEnv, TResult> | CodeStepEnvironment<TInput, TResult> | undefined, ctx?: CompileEnvironmentContext): CompiledEnvironment;
128
+ export declare function compileEnvironment<TInput, TEnv extends EnvRecord>(environment: InlineStepEnvironment<TInput, TEnv> | Exclude<CodeStepEnvironment<TInput>, string | EnvironmentHandle> | undefined, ctx?: CompileEnvironmentContext): CompiledInlineEnvironment | null;
129
+ export declare function compileEnvironment<TInput, TEnv extends EnvRecord>(environment: StepEnvironment<TInput, TEnv> | CodeStepEnvironment<TInput> | undefined, ctx?: CompileEnvironmentContext): CompiledEnvironment;