@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/automation-sandbox-post-copy-configure/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: automation-sandbox-post-copy-configure
-description: "Apply a Salesforce sandbox post-copy automation JSON config against a target org. For each entry, the skill derives the correct Tooling API sobject from the entry's `ConfigurationName`, verifies the derivation via a describe probe, resolves the record Id via SOQL-over-REST, then PATCHes the record via the compound `Metadata` field using `sf api request rest`. Use when the user asks to apply, run, execute, dry-run, or preview a post-copy or post-refresh config file (e.g. `post-copy-config.json`) against a sandbox. Trigger phrases: \"apply post-copy config\", \"run post-copy automation\", \"execute sandbox post-refresh JSON\", \"apply sandbox refresh config\", \"configure sandbox after refresh\". DO NOT TRIGGER for generating the config JSON from an SOP (delegate to `automation-sandbox-post-copy-config-generate`), or for deploying metadata XML."
+description: "Apply a Salesforce sandbox post-copy automation JSON config against a target org. For each entry, the skill derives the correct Tooling API sobject from the entry's `ConfigurationName`, verifies the derivation via a describe probe, resolves the record Id via SOQL-over-REST, then PATCHes the record via the compound `Metadata` field using `sf api request rest`. `ScheduledApex` entries run anonymous Apex `System.schedule(...)` via `sf apex run` (because `CronTrigger` is read-only) and verify via a `CronTrigger` SOQL read-back. Use when the user asks to apply, run, execute, dry-run, or preview a post-copy or post-refresh config file (e.g. `post-copy-config.json`) against a sandbox. Trigger phrases: \"apply post-copy config\", \"run post-copy automation\", \"execute sandbox post-refresh JSON\", \"apply sandbox refresh config\", \"configure sandbox after refresh\". DO NOT TRIGGER for generating the config JSON from an SOP (delegate to `automation-sandbox-post-copy-config-generate`), or for deploying metadata XML."
 allowed-tools: Bash Read Write
 metadata:
   relatedSkills:
     - "automation-sandbox-post-copy-config-generate"
     - "dx-org-permission-set-assign"
     - "platform-metadata-deploy"
-  version: "1.0"
+  version: "1.1"
   domains: ["Automation"]
   cliTools:
     - tool: ["curl"]
@@ -23,15 +23,15 @@ metadata:
 # Automation: Sandbox Post-Copy Configure
 
 Apply a Salesforce sandbox post-copy automation JSON config to a target
-org. The skill pins the Tooling API sobject **and** the record-lookup
-SOQL filter for the two canonical `ConfigurationName` values it has
-been calibrated against (`OutboundMessages`, `RemoteSiteSettings`); for
-any other `ConfigurationName` it derives a candidate from the entry
-value and verifies it against the live org's describe endpoint. Every
-entry — pinned or derived — must still pass Step B (describe returns
-200 with a `Metadata` compound field) before any PATCH is planned.
-Entries whose API cannot be identified or verified are surfaced in the
-summary and skipped — they are never guessed at.
+org. Three canonical `ConfigurationName` values are pinned:
+`OutboundMessages` and `RemoteSiteSettings` take the compound-`Metadata`
+PATCH route (Steps A–E); `ScheduledApex` takes the anonymous-Apex route
+(Step F), because `CronTrigger` is read-only in the Tooling API. Any
+other `ConfigurationName` is derived and describe-verified. Every A–E
+entry — pinned or derived — must pass Step B (describe returns 200 with
+a `Metadata` compound field) before any PATCH is planned; Step B does
+not apply to `ScheduledApex`. Entries whose API cannot be verified are
+surfaced in the summary and skipped — never guessed at.
 
 ## Tool Restrictions
 
@@ -92,6 +92,7 @@ substitute a different sobject name):**
 |-------------------|---------------------|--------------------|
 | `OutboundMessages`   | `WorkflowOutboundMessage` | `SELECT Id, FullName FROM WorkflowOutboundMessage WHERE EntityDefinition.QualifiedApiName = '<Fields.Object>'` — then client-side pick the row whose `FullName == '<Fields.Object>.<Label>'`. SOQL cannot filter on `FullName` directly for this sobject. |
 | `RemoteSiteSettings` | `RemoteProxy`             | `SELECT Id, SiteName FROM RemoteProxy WHERE SiteName = '<Label>'`. |
+| `ScheduledApex`      | `CronTrigger` (read-only — Anonymous Apex route, see Step F) | See Step F — pre-flight `SELECT Id FROM CronTrigger WHERE CronJobDetail.Name = '<escaped>'` gate. |
 
 For canonical entries use the pinned sobject and SOQL as-is; skip
 "derive". Do not invent `OutboundMessage`, `RemoteSiteSetting`, or
@@ -208,6 +209,13 @@ If the read-back value doesn't match the requested value, record
 `FAILED_VERIFY` — the PATCH returned 204 but the effect is not
 visible (usually a naming or permission issue).
 
+### Step F — Scheduled Apex (anonymous Apex route)
+
+`ScheduledApex` entries target the read-only `CronTrigger` sobject —
+Steps A–E do not apply. **Read `references/scheduled_apex_path.md`
+before executing** — it owns the full F-1 → F-4 recipe (pre-flight
+AMBIGUOUS gate, snippet build, `sf apex run`, verify, dry-run).
+
 ---
 
 ## IsActive semantics
@@ -233,22 +241,21 @@ side-files (`plan/phases.json`, `requests/*.request.json`, etc.) —
 inline every planned/actual request in the Markdown.
 
 **Phase enumeration is script-owned.** Run `node scripts/plan-phases.mjs
-<config.json>` and consume its `phases[]` output verbatim. Each entry
-carries `ordinal` (1-indexed phase number) and `executionOrder` (raw
-value, for the `(ExecutionOrder = <raw>)` heading annotation). Sparse
-values collapse (`1, 2, 5` → ordinals `1, 2, 3`). `IsActive:false`
+<config.json>` and consume its `phases[]` verbatim — each entry carries
+`ordinal` (1-indexed for headings) and `executionOrder` (raw, for
+`(ExecutionOrder = <raw>)`); sparse values collapse; `IsActive:false`
 entries are pre-marked `SKIP_INACTIVE`. See
 `references/execution_phasing.md` for the worked example.
 
-For dry-run entries the `HTTP` column is `—` (em-dash). End the
-summary with: `No PATCH requests were issued. To apply, re-run
-without the dry-run flag.`
-
 **Target-org resolution is script-owned.** Run `node
-scripts/resolve-target-org.mjs`; substitute the returned `.alias`
-into the header. Never emit `<env:SF_TARGET_ORG>` or `$SF_TARGET_ORG`
+scripts/resolve-target-org.mjs`; substitute the returned `.alias` into
+the header. Never emit `<env:SF_TARGET_ORG>` or `$SF_TARGET_ORG`
 verbatim.
 
+For dry-run entries the `HTTP` column is `—`. End the summary with:
+`No PATCH requests were issued. To apply, re-run without the dry-run
+flag.`
+
 ```markdown
 # Post-Copy Configure Run — <N> entries <planned|applied> against `<alias>`
 
@@ -287,12 +294,9 @@ glance. Outcome vocabulary: `SUCCESS`, `NOT_FOUND`, `AMBIGUOUS`,
 `SKIPPED_INACTIVE`, `SKIPPED`, `DRY_RUN`, `DELETE_NOT_SUPPORTED`,
 `NOT_ATTEMPTED`.
 
-**Scripts are internal.** The `plan-phases.mjs`, `map-metadata-key.mjs`,
-`classify-patch-result.mjs`, `resolve-target-org.mjs` invocations are
-implementation detail — do **not** inline their raw stdout, JSON
-output, or "I ran node …" narration into the summary Markdown or
-the printed response. Consume the JSON, use the returned values, and
-render the summary in the exact shape above.
+**Scripts are internal.** Do **not** inline raw `node scripts/…` stdout
+or "I ran node …" narration into the summary or the printed response —
+consume the JSON, use the returned values, render the exact shape above.
 
 ## Scope
 
@@ -326,24 +330,17 @@ Gather or infer before applying:
   the target sandbox. Never assume the default org — always confirm.
   If the user has not supplied one, list available orgs with `sf org
   list --json` and ask which to use.
-- **Dry-run flag** (optional, default `false`): Semantics —
-  **reads are ALLOWED, writes are FORBIDDEN**. Dry-run means the run
-  produces no mutation on the target org; it does NOT mean "no
-  network calls". You MUST still execute every read against the org:
-  the describe probe (Step B, `GET`), the SOQL Id lookup (Step C,
-  `sf data query`), and the record fetch (Step D-1, `GET`) — because
-  the plan's "would-be PATCH body" can only be accurate if the
-  agent has read the current `Metadata` block from the live record.
-  The ONLY skipped calls are the writes: Step D-3 (`PATCH`) and
-  Step E (post-PATCH verification). Never fabricate the current
-  Metadata; never emit a body containing invented keys. If a read
-  fails (401, 404, `NamedOrgNotFoundError`), surface the error and
-  stop — do not fall back to a from-memory plan. Use dry-run on the
-  first pass unless the user has explicitly asked to apply.
-- **Continue-on-error** (optional, default `true`): When true, a
-  failing entry does not abort the phase — the remaining entries in
-  the phase still execute, and the failure is reported in the
-  summary. When false, a failure aborts execution mid-phase.
+- **Dry-run flag** (optional, default `false`): **reads ALLOWED, writes
+  FORBIDDEN** — not "no network calls". Still run every read (Step B
+  describe `GET`, Step C SOQL, Step D-1 record `GET`); the plan's
+  would-be PATCH body is only accurate against the real Metadata block.
+  The ONLY skipped calls are Step D-3 (`PATCH`) and Step E (verify).
+  Never fabricate current Metadata or invent keys. On a read failure
+  (401, 404, `NamedOrgNotFoundError`), surface and stop — never fall
+  back to a from-memory plan. Prefer dry-run on the first pass.
+- **Continue-on-error** (optional, default `true`): true = failing
+  entries don't abort the phase (failure reported in the summary);
+  false = abort mid-phase.
 
 If the user supplies a clear config path and target alias, proceed
 without further questions.
@@ -352,9 +349,8 @@ without further questions.
 
 ## Workflow
 
-Every step executes real `sf` CLI commands via the Bash tool. Do NOT
-narrate the plan without actually running the commands — the point of
-this skill is to mutate the target org, not to describe how.
+Every step executes real `sf` CLI commands via Bash. Do NOT narrate the
+plan without running the commands — this skill mutates the target org.
 
 1. **Read and validate the config JSON** — load the file with the
    Read tool. Every entry must be a JSON object with the five
@@ -371,18 +367,21 @@ this skill is to mutate the target org, not to describe how.
    `references/execution_phasing.md` for the concurrency cap.
 
 4. **Per-entry describe-verify pass** — for each distinct
-   `ConfigurationName`, run Step A + Step B once and cache the
-   verified sobject. Any `ConfigurationName` failing Step B marks
-   every entry with that name as `API_NOT_IDENTIFIED`.
+   `ConfigurationName` NOT equal to `ScheduledApex`, run Step A +
+   Step B once and cache the verified sobject. Any `ConfigurationName`
+   failing Step B marks every entry with that name as
+   `API_NOT_IDENTIFIED`. `ScheduledApex` skips describe-verify — it
+   uses the Anonymous Apex route (Step F), not compound-`Metadata`
+   PATCH.
 
 5. **Per-entry apply pass** — for each entry inside each phase:
-   - Entries pre-marked `SKIP_INACTIVE` by plan-phases → record
+   - `SKIP_INACTIVE` pre-marked by plan-phases → record
      `SKIPPED_INACTIVE`, add a Follow-ups bullet, continue.
-   - Else run Step C (resolve Id), then Step D (GET+mutate+PATCH),
-     then Step E (verify). If `--dry-run` is true, still run Step C
-     and D-1/D-2 so the printed plan reflects the real merged
-     payload — skip only D-3 (the PATCH) and Step E, then record
-     `DRY_RUN`.
+   - `ScheduledApex` → Step F (F-1 pre-flight, F-2 build, F-3 run,
+     F-4 verify). Dry-run: run F-1 + F-2 only; record `DRY_RUN`.
+   - All others → Step C (Id), Step D (GET+mutate+PATCH), Step E
+     (verify). Dry-run: run C + D-1/D-2 (so the printed plan reflects
+     the real merged payload); skip D-3 and E; record `DRY_RUN`.
 
 6. **Between phases** — wait for every entry in the current phase to
    complete before starting the next.
@@ -415,9 +414,9 @@ that file before deviating from the Step A–E procedure.
 | Need | Delegate to |
 |------|-------------|
 | Turn a customer SOP into the JSON config this skill consumes | `automation-sandbox-post-copy-config-generate` |
-| Deploy Salesforce metadata XML (Custom Labels, Named Credentials, etc.) that lives outside the compound-Metadata Tooling API pattern | The matching `generating-*` skill + a metadata deploy flow |
-| Create new records that do not yet exist on the target org | `platform-metadata-deploy` after generating the metadata XML |
-| Assign permission sets required to run the API calls | `dx-org-permission-set-assign` |
+| Deploy metadata XML outside the compound-Metadata Tooling pattern | Matching `generating-*` skill + a metadata deploy flow |
+| Create new records that do not yet exist on the target org | `platform-metadata-deploy` |
+| Assign permission sets required for the API calls | `dx-org-permission-set-assign` |
 
 ---
 
@@ -425,14 +424,19 @@ that file before deviating from the Step A–E procedure.
 
 | File | When to read |
 |------|-------------|
-| `references/api_endpoints.md` | Steps A–E — the full generic recipe with worked examples (OBM, RSS) and the camelCase-field convention |
-| `references/execution_phasing.md` | Step 3 (workflow) — the grouping rules and the intra-phase concurrency cap. `scripts/plan-phases.mjs` is the executable source-of-truth for phase enumeration; this file explains the model behind it |
-| `scripts/plan-phases.mjs` | Step 3 (workflow) — deterministic phase planner (invoke, then read its output) |
-| `scripts/map-metadata-key.mjs` | Step D-2 — deterministic Metadata-key resolver (override table + case rule + existence check) |
-| `scripts/classify-patch-result.mjs` | Step D-4 — deterministic HTTP-outcome classifier (SUCCESS vs FAILED) |
-| `scripts/resolve-target-org.mjs` | Canonical output shape — deterministic target-org alias resolver |
-| `references/authentication.md` | Step 2 (workflow) — for the session-check recipe and how to handle 401 mid-run |
-| `references/rules_gotchas.md` | Before deviating from Step A–E — load-bearing invariants and canonical runtime-failure responses |
-| `assets/api_request_templates.json` | Steps A–E — the generic template for describe / lookup / GET+PATCH with placeholder keys |
-| `examples/sample_config_input.json` | Step 1 (workflow) — shape of the config JSON this skill consumes |
-| `examples/sample_execution_summary.md` | Step 7 (workflow) — the shape of the summary report shown to the user |
+| `references/api_endpoints.md` | Steps A–E — full generic recipe with OBM / RSS worked examples and the camelCase-field convention |
+| `references/scheduled_apex_path.md` | Step F — anonymous Apex route for `ScheduledApex` entries |
+| `references/execution_phasing.md` | Step 3 (workflow) — phase-grouping model behind `scripts/plan-phases.mjs` |
+| `references/authentication.md` | Step 2 — session check + how to handle 401 mid-run |
+| `references/rules_gotchas.md` | Before deviating from Step A–E — invariants and runtime-failure responses |
+| `scripts/plan-phases.mjs` | Step 3 — deterministic phase planner |
+| `scripts/map-metadata-key.mjs` | Step D-2 — deterministic Metadata-key resolver |
+| `scripts/classify-patch-result.mjs` | Step D-4 — deterministic HTTP-outcome classifier |
+| `scripts/resolve-target-org.mjs` | Canonical output shape — target-org alias resolver |
+| `scripts/build-scheduled-apex.mjs` | Step F-2 — anonymous-Apex snippet builder |
+| `scripts/soql-escape-job-name.mjs` | Step F-1/F-4 — SOQL-escape `JobName` |
+| `assets/api_request_templates.json` | Steps A–E — generic describe / lookup / GET+PATCH template |
+| `assets/scheduled_apex_template.apex` | Step F-2 — anonymous Apex template with `{{JOB_NAME}}` / `{{CRON_EXPRESSION}}` / `{{APEX_CLASS_NAME}}` placeholders |
+| `examples/sample_config_input.json` | Step 1 — shape of the config JSON this skill consumes |
+| `examples/sample_scheduled_apex_config.json` | Step 1 — shape of a `ScheduledApex` config entry |
+| `examples/sample_execution_summary.md` | Step 7 — shape of the summary report shown to the user |

package/skills/automation-sandbox-post-copy-configure/assets/scheduled_apex_template.apex

@@ -0,0 +1,13 @@
+// Anonymous Apex template — schedules a Salesforce Schedulable class.
+//
+// Placeholders (single-quote-escaped by scripts/build-scheduled-apex.mjs):
+//   {{JOB_NAME}}         — value of CronTrigger.CronJobDetail.Name after scheduling.
+//   {{CRON_EXPRESSION}}  — 6- or 7-field Salesforce cron expression.
+//   {{APEX_CLASS_NAME}}  — bare identifier of a class that implements Schedulable.
+//
+// Prerequisites (enforced upstream — see references/scheduled_apex_path.md):
+//   1. Step F-1 has already asserted no CronTrigger with CronJobDetail.Name = '{{JOB_NAME}}'
+//      exists on the target org — otherwise System.schedule throws.
+//   2. The {{APEX_CLASS_NAME}} class exists on the target org — sandbox refresh
+//      copies class metadata, so this is normally satisfied post-refresh.
+System.schedule('{{JOB_NAME}}', '{{CRON_EXPRESSION}}', new {{APEX_CLASS_NAME}}());

package/skills/automation-sandbox-post-copy-configure/examples/sample_scheduled_apex_config.json

@@ -0,0 +1,13 @@
+[
+  {
+    "ConfigurationName": "ScheduledApex",
+    "Label": "Nightly Data Sync",
+    "Fields": {
+      "ApexClassName": "NightlyDataSyncScheduler",
+      "CronExpression": "0 0 2 * * ?",
+      "JobName": "Nightly Data Sync"
+    },
+    "IsActive": true,
+    "ExecutionOrder": 3
+  }
+]

package/skills/automation-sandbox-post-copy-configure/references/scheduled_apex_path.md

@@ -0,0 +1,155 @@
+# Step F — Scheduled Apex (anonymous Apex route)
+
+`ScheduledApex` entries in the post-copy config target the `CronTrigger`
+sobject, which is **read-only** in the Tooling API — there is no
+compound `Metadata` field, so Steps A–E (describe → SOQL → GET+PATCH)
+cannot apply. Instead this route runs anonymous Apex
+`System.schedule(...)` via `sf apex run` and verifies via a
+`CronTrigger` SOQL read-back.
+
+## Fields shape
+
+Every `ScheduledApex` entry must carry these three keys under `Fields`:
+
+| Key | Meaning |
+|-----|---------|
+| `ApexClassName` | Bare Apex identifier of the class that implements `Schedulable`. |
+| `CronExpression` | Salesforce cron expression (6- or 7-field). |
+| `JobName` | Human-readable job name. Appears in Setup > Scheduled Jobs; equals `CronTrigger.CronJobDetail.Name` post-schedule. |
+
+If any of the three is missing, mark the entry `API_NOT_IDENTIFIED` and
+skip. Never fabricate one from the others.
+
+## Prerequisites
+
+The Apex `Schedulable` class named by `ApexClassName` must already exist
+on the target sandbox. Sandbox refresh copies class metadata from source
+to target, so this is normally satisfied on a fresh refresh — the reason
+scheduled *jobs* need re-creation is that `CronTrigger` records (runtime
+state) don't copy, not that the classes don't.
+
+If the class is genuinely missing, F-3 (`sf apex run`) fails at compile
+with `Variable does not exist: <ApexClassName>` — the outcome becomes
+`FAILED` and the customer follows the Cross-Skill Integration row on
+`platform-metadata-deploy` to deploy the class before re-running this
+skill.
+
+## F-1 — Pre-flight AMBIGUOUS check
+
+`System.schedule` throws `AlreadyScheduledException` if a job with the
+same name already exists. Query first to avoid that path — and per skill
+policy, do NOT auto-abort an existing job; surface it as `AMBIGUOUS` so
+the customer decides.
+
+`JobName` is human-readable and may legitimately contain an apostrophe
+(e.g. `Owner's nightly job`). Never inline it into the SOQL literal
+directly — escape it via the deterministic helper first, which also
+rejects the same characters `scripts/build-scheduled-apex.mjs` rejects
+(newlines/backslashes), so an input that passes F-1 will also pass F-2:
+
+```bash
+JOB_NAME_LITERAL=$(node scripts/soql-escape-job-name.mjs "<Fields.JobName>") || {
+  # Non-zero exit → outcome FAILED with stderr in Follow-ups; skip F-2/F-3/F-4.
+  exit 1
+}
+SOQL="SELECT Id FROM CronTrigger WHERE CronJobDetail.Name = '$JOB_NAME_LITERAL'"
+sf data query --json --query "$SOQL" > /tmp/entry-<Slug>-cron.json
+COUNT=$(jq -r '.result.totalSize' /tmp/entry-<Slug>-cron.json)
+```
+
+Outcomes:
+
+- `COUNT == 0` → proceed to F-2.
+- `COUNT >= 1` → outcome `AMBIGUOUS`. Add a Follow-ups bullet listing
+  the entry's `Fields.JobName` and every returned `CronTrigger.Id`.
+  Do not attempt to schedule.
+
+In dry-run, still run F-1 — it is a read.
+
+## F-2 — Build the anonymous Apex snippet
+
+Never author the snippet from memory — Apex string escaping is a common
+foot-gun. Use the deterministic builder:
+
+```bash
+node scripts/build-scheduled-apex.mjs \
+  "<Fields.JobName>" \
+  "<Fields.CronExpression>" \
+  "<Fields.ApexClassName>" \
+  assets/scheduled_apex_template.apex \
+  > /tmp/entry-<Slug>.apex
+```
+
+The script:
+
+- Verifies `CronExpression` is 6- or 7-field whitespace-separated.
+- Verifies `ApexClassName` matches `^[A-Za-z_][A-Za-z0-9_]*$`.
+- Rejects newlines and backslashes in any input (would either break the
+  string literal or enable Apex injection).
+- Single-quote-escapes `JobName` and `CronExpression` for embedding in
+  the Apex single-quoted string.
+- Writes the substituted `.apex` snippet to stdout.
+
+Non-zero exit → outcome `FAILED` with stderr in Follow-ups.
+
+## F-3 — Execute the snippet
+
+```bash
+sf apex run --file /tmp/entry-<Slug>.apex --json \
+  > /tmp/entry-<Slug>-apex.json
+```
+
+Classify from the JSON response:
+
+| `.result.compiled` | `.result.success` | Outcome | Follow-ups body |
+|--------------------|-------------------|---------|-----------------|
+| `false` | (any)   | `FAILED` | `.result.compileProblem`, `.result.line`, `.result.column` |
+| `true`  | `false` | `FAILED` | `.result.exceptionMessage`, `.result.exceptionStackTrace` |
+| `true`  | `true`  | proceed to F-4 | — |
+
+Skip F-3 entirely in dry-run and record `DRY_RUN`.
+
+## F-4 — Verify the job scheduled
+
+Reuse `$JOB_NAME_LITERAL` from F-1 — it is the same JobName, already
+SOQL-escaped and validated:
+
+```bash
+SOQL="SELECT Id, State, NextFireTime, CronExpression FROM CronTrigger WHERE CronJobDetail.Name = '$JOB_NAME_LITERAL'"
+sf data query --json --query "$SOQL" > /tmp/entry-<Slug>-verify.json
+```
+
+Outcomes:
+
+- 0 rows → `FAILED_VERIFY` (apex reported success but no CronTrigger
+  materialized — usually a permission or platform limits issue).
+- ≥1 row where `.CronExpression == '<Fields.CronExpression>'` → `SUCCESS`.
+- ≥1 row with a different `CronExpression` → `FAILED_VERIFY` (something
+  else claimed the name after F-1 saw it clear).
+
+Skip F-4 entirely in dry-run (nothing to verify).
+
+## Summary shape for a Step F entry
+
+Reuse the phase table from the canonical output shape:
+
+- `Sobject` column reads `CronTrigger`.
+- `Describe` column reads `—` (no describe probe on this route).
+- "Planned request" / "Request executed" is the anonymous Apex snippet
+  path (`/tmp/entry-<Slug>.apex`) and its contents inline, not a PATCH
+  path/body.
+- `HTTP` column reads `—` (no direct HTTP status; `sf apex run` bundles
+  compile+execute into one response).
+
+## Dry-run recap
+
+| Sub-step | Dry-run behavior |
+|----------|------------------|
+| F-1 SOQL pre-flight | run (read) |
+| F-2 snippet build (writes to `/tmp` only) | run |
+| F-3 `sf apex run` | SKIP → record `DRY_RUN` |
+| F-4 verify SOQL | SKIP (nothing to verify) |
+
+The "Planned request" printed in the dry-run summary for a Step F entry
+is the full contents of the built `.apex` snippet, so the customer can
+audit exactly what would have executed.

package/skills/automation-sandbox-post-copy-configure/scripts/build-scheduled-apex.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Deterministic Step F-2 helper: render assets/scheduled_apex_template.apex
+// with a config entry's JobName / CronExpression / ApexClassName. Emits
+// the substituted snippet to stdout; non-zero exit on any validation
+// failure with a single-line human-readable reason on stderr.
+//
+// Kept out of SKILL.md prose per authoring standard A9 — string escaping
+// and cron/identifier validation are deterministic and belong in scripts/.
+
+import { readFileSync } from 'node:fs';
+
+const [, , jobName, cronExpression, apexClassName, templatePath] = process.argv;
+
+if (!jobName || !cronExpression || !apexClassName || !templatePath) {
+  process.stderr.write(
+    'usage: node build-scheduled-apex.mjs <JobName> <CronExpression> <ApexClassName> <template-path>\n'
+  );
+  process.exit(2);
+}
+
+// Reject characters that break out of the Apex single-quoted string
+// literal we substitute into. Newlines are a compile error; backslash
+// is not a general escape in Apex string literals and lets a crafted
+// value inject arbitrary Apex.
+const forbidden = /[\r\n\\]/;
+for (const [name, value] of [
+  ['JobName', jobName],
+  ['CronExpression', cronExpression],
+  ['ApexClassName', apexClassName],
+]) {
+  if (forbidden.test(value)) {
+    process.stderr.write(
+      `ERROR: ${name} contains a newline or backslash: ${JSON.stringify(value)}\n`
+    );
+    process.exit(2);
+  }
+}
+
+const cronFields = cronExpression.trim().split(/\s+/).length;
+if (cronFields !== 6 && cronFields !== 7) {
+  process.stderr.write(
+    `ERROR: CronExpression must be 6 or 7 whitespace-separated fields; got ${cronFields}: ${JSON.stringify(cronExpression)}\n`
+  );
+  process.exit(2);
+}
+
+if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(apexClassName)) {
+  process.stderr.write(
+    `ERROR: ApexClassName must be a bare Apex identifier (letters, digits, underscore, not starting with a digit): ${JSON.stringify(apexClassName)}\n`
+  );
+  process.exit(2);
+}
+
+const escapeApexSingleQuoted = (s) => s.replaceAll("'", "\\'");
+
+const template = readFileSync(templatePath, 'utf8');
+const rendered = template
+  .replaceAll('{{JOB_NAME}}', escapeApexSingleQuoted(jobName))
+  .replaceAll('{{CRON_EXPRESSION}}', escapeApexSingleQuoted(cronExpression))
+  .replaceAll('{{APEX_CLASS_NAME}}', apexClassName);
+
+process.stdout.write(rendered);

package/skills/automation-sandbox-post-copy-configure/scripts/soql-escape-job-name.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Deterministic JobName → SOQL-safe literal helper for Step F-1 / F-4
+// pre-flight and verify SOQL. A human-readable JobName may legitimately
+// contain characters (e.g. an apostrophe in "Owner's nightly job") that
+// break out of a raw single-quoted SOQL literal. This helper rejects
+// characters that would also break the F-2 Apex snippet (kept in
+// lockstep with build-scheduled-apex.mjs) and escapes single quotes for
+// SOQL, so both the pre-flight query and the anonymous Apex snippet
+// operate on the same validated JobName.
+//
+// Exits 0 with the escaped literal on stdout, or non-zero with a
+// single-line reason on stderr.
+
+const [, , jobName] = process.argv;
+
+if (jobName === undefined) {
+  process.stderr.write('usage: node soql-escape-job-name.mjs <JobName>\n');
+  process.exit(2);
+}
+
+if (/[\r\n\\]/.test(jobName)) {
+  process.stderr.write(
+    `ERROR: JobName contains a newline or backslash: ${JSON.stringify(jobName)}\n`
+  );
+  process.exit(2);
+}
+
+process.stdout.write(jobName.replaceAll("'", "\\'"));