Skip to content

docs(authoring): adopt scripts/ as the script packaging convention - #90

Merged
Justinvolved merged 3 commits into
mainfrom
docs/scripts-packaging-convention
Sep 7, 2026
Merged

docs(authoring): adopt scripts/ as the script packaging convention#90
Justinvolved merged 3 commits into
mainfrom
docs/scripts-packaging-convention

Conversation

@Justinvolved

@Justinvolved Justinvolved commented Aug 28, 2026

Copy link
Copy Markdown
Collaborator

What

Docs-only PR that fixes the rules before any script ships. Version 4.20.0 -> 4.21.0.

  • .claude/skills/dw-skill-authoring/SKILL.md, new section Shipping scripts: the script contract (scripts/ layout per the Agent Skills spec; language per job with the runtime declared in compatibility:; language-neutral rules: actionable header with a READ-ONLY / WRITES opener, explicit parameters, exit codes, dry-run default beyond one row, connection discovery order with no default host/port/path/token, environment-only secrets, encoding; a PowerShell profile with comment-based help, SupportsShouldProcess, one shared module in dw-data-access, dw-setup-install self-contained; a Python profile with argparse and --dry-run/--apply; linked ## Scripts table, forward-slash invocations). Script imports count toward bundle closure.
  • skills/dw-demo-foldback/references/fold-back-workflow.md, new Step 1c: lifting a script from a demo build. Recurrence bar, script-specific sanitization classes, one-lesson-one-home for the superseded prose, retiring the demo copy, and the smoke-test rule (write scripts local-first; a hosted install only afterwards and under dw-demo-hosted shared-install discipline).
  • skills/dw-demo-base/references/setup-checks.md: install-grade fix for a missing pwsh.
  • CLAUDE.md, README.md, CHANGELOG.md, marketplace.json version.

Two things to review deliberately

  1. Language per job, runtime declared. PowerShell 7 is the default for anything that touches a Dynamicweb install on a Windows host; every PowerShell script starts with #Requires -Version 7.0, PowerShell 7 is a machine prerequisite installed by the setup preflight next to git, gh and node, and scripts never branch on the version. A skill may ship a script in another language (Python, Bash, JavaScript) where that fits better, e.g. text transforms over template files; the requirement is that the runtime is declared in the skill's compatibility: frontmatter, not that it is PowerShell. The demo chain already mandates pwsh 7+ (setup-checks.md); the four existing dw-setup-install scripts are the only 5.1-compatible code and carry a curl.exe -k fallback plus an unguarded ConvertFrom-Json -AsHashtable that silently empties .mcp.json under 5.1. The next PR removes that dual target.
  2. That recurring demo-build operations get scripted at all. The survey behind this found the same eight operations re-implemented across engagements (Admin API / MCP wrapper about 20 times, RunSql task runner 4 verbatim copies, guarded host restart 3 copies with one recorded sibling-host kill, index build, readiness verify, PII scan, stock-Swift debrand, mojibake census) while the repo holds them only as fenced prose. The convention here is the precondition for shipping those as one shared module plus seven scripts, one PR each.

History

Opened first as #89, stacked on #87; GitHub auto-closed it when #87's branch was deleted on merge. Same single commit, now rebased onto main.

Checks

  • python scripts/validate-skills.py: 0 errors (7 pre-existing length warnings, untouched).
  • node scripts/build-manifest.mjs --check: up to date.
  • Sanitization grep over the diff: clean.

Defines how runnable scripts ship inside skills before the first wave of
shared scripts lands: the file contract, PowerShell 7 as the single
target with #Requires -Version 7.0, connection discovery and secrets
rules, bundle closure for script imports, the fold-back gates for
lifting a script out of a demo build, and the smoke-test rule for write
scripts. Docs only; the validator checks and the migration of the four
existing dw-setup-install scripts follow in the next PR.
@Justinvolved
Justinvolved force-pushed the docs/scripts-packaging-convention branch from c1cd2fd to 0867f93 Compare September 1, 2026 08:20
@Justinvolved
Justinvolved merged commit 919f81b into main Sep 7, 2026
1 check passed
@Justinvolved
Justinvolved deleted the docs/scripts-packaging-convention branch September 7, 2026 15:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant