fix(sandboxes): spend the build budget after validation, conceal workspace ids on item routes, read manifest files in the CLI

Author: icecrasher321

apps/docs/content/docs/cli/reference.mdx

@@ -2761,9 +2761,9 @@ sim sandboxes create [options]
 | --- | --- | --- |
 | `--name <value>` | Yes | Display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | Yes | Dependency ecosystem: `javascript` installs from npm, `python` from PyPI. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. Blank entries and `#` comments are ignored. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. Blank entries and `#` comments are ignored. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Debian packages installed into the sandbox image, one per entry. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Debian packages installed into the sandbox image, one per entry. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 
 </CommandTable>
 
@@ -2860,9 +2860,9 @@ sim sandboxes update <sandboxId> [options]
 | --- | --- | --- |
 | `--name <value>` | No | New display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | No | Replacement dependency ecosystem. The whole spec is revalidated against it, so a Python dependency list does not survive a switch to JavaScript. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Replacement managed CLI list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 
 </CommandTable>
 

apps/docs/content/docs/cli/sandboxes.mdx

@@ -25,9 +25,9 @@ Create Sandbox (personal API key required)
 | --- | --- | --- |
 | `--name <value>` | Yes | Display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | Yes | Dependency ecosystem: `javascript` installs from npm, `python` from PyPI. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. Blank entries and `#` comments are ignored. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. Blank entries and `#` comments are ignored. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Debian packages installed into the sandbox image, one per entry. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Debian packages installed into the sandbox image, one per entry. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 
 </CommandTable>
 
@@ -120,8 +120,8 @@ Update Sandbox (personal API key required)
 | --- | --- | --- |
 | `--name <value>` | No | New display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | No | Replacement dependency ecosystem. The whole spec is revalidated against it, so a Python dependency list does not survive a switch to JavaScript. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Replacement managed CLI list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
 
 </CommandTable>

apps/docs/openapi-v2-resources.json

@@ -2143,7 +2143,7 @@
       "post": {
         "operationId": "createSandbox",
         "summary": "Create Sandbox",
-        "description": "Create a sandbox and schedule its image build. The name must be unique within the workspace. A dependency or system-package entry the builder cannot accept is a `400` whose `error.details` names the field and the offending entries. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. Builds cost compute, so every write in a workspace draws on one shared budget, and a burst is refused with `429` and a `Retry-After` header. A workspace API key is rejected with `403`; use a personal API key.",
+        "description": "Create a sandbox. The name must be unique within the workspace. Where the deployment prebuilds dependency images, the build is scheduled and reported through `buildStatus`; a deployment that installs at run time, or a sandbox with nothing to install, has no build and reports `buildStatus: null`. A dependency or system-package entry the builder cannot accept is a `400` whose `error.details` names the field and the offending entries. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. Builds cost compute, so every write in a workspace draws on one shared budget, and a burst is refused with `429` and a `Retry-After` header. A workspace API key is rejected with `403`; use a personal API key.",
         "tags": ["Sandboxes"],
         "requestBody": {
           "required": true,
@@ -2158,7 +2158,7 @@
         },
         "responses": {
           "201": {
-            "description": "The sandbox was created and its build scheduled.",
+            "description": "The sandbox was created; a build is scheduled where the deployment prebuilds images.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -2290,7 +2290,7 @@
       "patch": {
         "operationId": "updateSandbox",
         "summary": "Update Sandbox",
-        "description": "Update the supplied sandbox fields and rebuild the image. Omitted fields retain their stored values; a supplied list replaces the whole list; names must remain unique within the workspace. Re-sending an unchanged spec after a failed build retries the build. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. Builds cost compute, so every write in a workspace draws on one shared budget, and a burst is refused with `429` and a `Retry-After` header. A workspace API key is rejected with `403`; use a personal API key.",
+        "description": "Update the supplied sandbox fields. Omitted fields retain their stored values; a supplied list replaces the whole list; names must remain unique within the workspace. Where the deployment prebuilds dependency images, a changed spec is rebuilt and re-sending an unchanged spec after a failed build retries it; a deployment that installs at run time, or a spec with nothing to install, has no build and reports `buildStatus: null`. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. Builds cost compute, so every write in a workspace draws on one shared budget, and a burst is refused with `429` and a `Retry-After` header. A workspace API key is rejected with `403`; use a personal API key.",
         "tags": ["Sandboxes"],
         "parameters": [
           {
@@ -2373,7 +2373,7 @@
       "delete": {
         "operationId": "deleteSandbox",
         "summary": "Delete Sandbox",
-        "description": "Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed, and the image is released once nothing else shares it. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. Builds cost compute, so every write in a workspace draws on one shared budget, and a burst is refused with `429` and a `Retry-After` header. A workspace API key is rejected with `403`; use a personal API key.",
+        "description": "Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed. Any prebuilt image is released once nothing else shares it. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. Builds cost compute, so every write in a workspace draws on one shared budget, and a burst is refused with `429` and a `Retry-After` header. A workspace API key is rejected with `403`; use a personal API key.",
         "tags": ["Sandboxes"],
         "parameters": [
           {
@@ -7001,7 +7001,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Create sandbox response",
-        "description": "The created sandbox, with its build still pending.",
+        "description": "The created sandbox. `buildStatus` is `pending` while an image builds and `null` where nothing is built.",
         "examples": [
           {
             "data": {
@@ -7155,7 +7155,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Update sandbox response",
-        "description": "The updated sandbox, with its rebuild pending.",
+        "description": "The updated sandbox. `buildStatus` is `pending` while an image rebuilds and `null` where nothing is built.",
         "examples": [
           {
             "data": {

apps/sim/app/api/v2/sandboxes/[sandboxId]/route.test.ts

@@ -166,6 +166,18 @@ describe('/api/v2/sandboxes/[sandboxId]', () => {
     })
   })
 
+  it('answers a missing workspace as a missing sandbox, not as a missing workspace', async () => {
+    mocks.get.mockRejectedValue(new OrchestrationError('not_found', 'Workspace not found'))
+
+    const response = await GET(request('GET'), context)
+
+    expect(response.status).toBe(404)
+    expect((await response.json()).error).toEqual({
+      code: 'NOT_FOUND',
+      message: 'Sandbox not found',
+    })
+  })
+
   it('keeps an in-workspace role refusal a 403 with its remedy', async () => {
     mocks.update.mockRejectedValue(new InsufficientWorkspacePermissionsError())
 

apps/sim/app/api/v2/sandboxes/utils.ts

@@ -37,9 +37,21 @@ export function renderSandboxError(error: unknown) {
   return v2CaughtOrchestrationError(error)
 }
 
+/**
+ * The item routes answer every absence as a missing sandbox. A missing or
+ * archived workspace must not read differently from a workspace the caller has
+ * no reach into, or the message becomes an oracle for which workspace ids exist.
+ */
+function renderSandboxResourceError(error: unknown) {
+  if (asOrchestrationError(error)?.code === 'not_found') {
+    return v2Error('NOT_FOUND', SANDBOX_NOT_FOUND_MESSAGE)
+  }
+  return renderSandboxError(error)
+}
+
 export const sandboxCollectionErrorPolicy: V2ErrorPolicy = { render: renderSandboxError }
 
 export const sandboxResourceErrorPolicy = createV2ResourceConcealmentPolicy({
   notFoundMessage: SANDBOX_NOT_FOUND_MESSAGE,
-  render: renderSandboxError,
+  render: renderSandboxResourceError,
 })

apps/sim/app/api/workspaces/[id]/sandboxes/error-policy.test.ts

@@ -118,4 +118,22 @@ describe('internal sandbox error policy', () => {
       internalSandboxResourceErrorPolicy.project(new InsufficientWorkspacePermissionsError())
     ).toMatchObject({ status: 403 })
   })
+
+  /**
+   * A missing workspace and a workspace the caller cannot reach are both a
+   * missing sandbox on item routes; a distinct message would tell a probe which
+   * workspace ids exist. The collection policy keeps the specific message.
+   */
+  it('answers a missing workspace on item routes as a missing sandbox', () => {
+    const missingWorkspace = new OrchestrationError('not_found', 'Workspace not found')
+
+    expect(internalSandboxResourceErrorPolicy.project(missingWorkspace)).toMatchObject({
+      status: 404,
+      body: { error: 'Sandbox not found' },
+    })
+    expect(internalSandboxErrorPolicy.project(missingWorkspace)).toMatchObject({
+      status: 404,
+      body: { error: 'Workspace not found' },
+    })
+  })
 })

apps/sim/app/api/workspaces/[id]/sandboxes/error-policy.ts

@@ -54,8 +54,17 @@ export const internalSandboxErrorPolicy = extendInternalErrorPolicy(
   }
 )
 
-/** The item routes conceal a caller with no reach into the workspace as a missing sandbox. */
+/**
+ * The item routes answer every absence, and every concealed refusal, as a
+ * missing sandbox. A missing or archived workspace must not read differently
+ * from a workspace the caller has no reach into, or the message becomes an
+ * oracle for which workspace ids exist.
+ */
 export const internalSandboxResourceErrorPolicy = createInternalResourceConcealmentPolicy({
-  base: internalSandboxErrorPolicy,
+  base: extendInternalErrorPolicy(internalSandboxErrorPolicy, (error) =>
+    asOrchestrationError(error)?.code === 'not_found'
+      ? internalErrorResponse(404, { error: SANDBOX_NOT_FOUND_MESSAGE })
+      : null
+  ),
   notFoundMessage: SANDBOX_NOT_FOUND_MESSAGE,
 })

apps/sim/lib/api/contracts/v2/openapi/resources.ts

@@ -1255,9 +1255,12 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       operationId: 'createSandbox',
       summary: 'Create Sandbox',
-      description: `Create a sandbox and schedule its image build. The name must be unique within the workspace. A dependency or system-package entry the builder cannot accept is a \`400\` whose \`error.details\` names the field and the offending entries. ${SANDBOX_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Create a sandbox. The name must be unique within the workspace. Where the deployment prebuilds dependency images, the build is scheduled and reported through \`buildStatus\`; a deployment that installs at run time, or a sandbox with nothing to install, has no build and reports \`buildStatus: null\`. A dependency or system-package entry the builder cannot accept is a \`400\` whose \`error.details\` names the field and the offending entries. ${SANDBOX_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'The sandbox was created and its build scheduled.' },
+      success: {
+        description:
+          'The sandbox was created; a build is scheduled where the deployment prebuilds images.',
+      },
     }),
     {
       query: v2CreateSandboxContract.query,
@@ -1280,7 +1283,7 @@ const declaredRoutes = [
         v2CreateSandboxContract.response.schema,
         'CreateSandboxResponse',
         'Create sandbox response',
-        'The created sandbox, with its build still pending.',
+        'The created sandbox. `buildStatus` is `pending` while an image builds and `null` where nothing is built.',
         [{ data: { ...SANDBOX_EXAMPLE, buildStatus: 'pending', builtAt: null } }]
       ),
     }
@@ -1322,7 +1325,7 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       operationId: 'updateSandbox',
       summary: 'Update Sandbox',
-      description: `Update the supplied sandbox fields and rebuild the image. Omitted fields retain their stored values; a supplied list replaces the whole list; names must remain unique within the workspace. Re-sending an unchanged spec after a failed build retries the build. ${SANDBOX_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Update the supplied sandbox fields. Omitted fields retain their stored values; a supplied list replaces the whole list; names must remain unique within the workspace. Where the deployment prebuilds dependency images, a changed spec is rebuilt and re-sending an unchanged spec after a failed build retries it; a deployment that installs at run time, or a spec with nothing to install, has no build and reports \`buildStatus: null\`. ${SANDBOX_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated sandbox.' },
     }),
@@ -1345,7 +1348,7 @@ const declaredRoutes = [
         v2UpdateSandboxContract.response.schema,
         'UpdateSandboxResponse',
         'Update sandbox response',
-        'The updated sandbox, with its rebuild pending.',
+        'The updated sandbox. `buildStatus` is `pending` while an image rebuilds and `null` where nothing is built.',
         [
           {
             data: {
@@ -1364,7 +1367,7 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       operationId: 'deleteSandbox',
       summary: 'Delete Sandbox',
-      description: `Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed, and the image is released once nothing else shares it. ${SANDBOX_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed. Any prebuilt image is released once nothing else shares it. ${SANDBOX_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The sandbox was deleted.' },
     }),