@webship.co/workspace 1.0.0-alpha1 → 1.0.0-beta2

package/core/docs/testing.md

@@ -0,0 +1,15 @@
+# Testing
+
+## The core
+
+- Unit: `node --test core/workspace-app/tests/unit/*.test.js` (Node's own runner). The plugin system has its own file, `plugin-system.test.js`, which drives `plugins.sh` against a temporary tree with `WORKSPACE_PLUGINS_NO_RESTART=1`, so a test never restarts the dashboard that serves this machine.
+- Browser: `cd core/workspace-app && ddev test-dashboard browser` runs the webship-js (Playwright + cucumber-js) features under `tests/features` against the live dashboard, one scenario at a time. Every installed plugin's `features/*.feature` is placed under `tests/features/plugins/<name>/`, so the suite covers what is actually on.
+- Scripts: `bash core/scripts/tests/cmd-smoke-test.sh` parses every `cmd-*.sh`.
+
+## A plugin
+
+`npm test` in the plugin's folder builds it (TypeScript to `dist/`) and runs its compiled tests. Its CI workflow does the same on push.
+
+## The rule
+
+A change lands through an issue and a pull request on the repository it belongs to, and is reviewed once the browser suite passes on a dashboard with the plugins installed from npm.

package/core/docs/workspaces.md

@@ -0,0 +1,25 @@
+# Workspaces
+
+A workspace is a folder under the workspace root with a `workspace.<key>.settings.yml` in `core/config` and a set of `cmd-*.sh` commands. `settings.yml`'s `workspaces:` list says which folders exist and in what order the dashboard shows them.
+
+## Types
+
+| Type | What the folder holds | What a row offers |
+| --- | --- | --- |
+| `sites` | Real projects with a DDEV environment | build, start/stop, launch, back up, clone, remove, the plugins' menus |
+| `code` | Repositories checked out to work on | backup, remove, the menus that make sense without a site |
+| `files` | Markdown items, edited in place | open, edit |
+| `media` | Recordings and images | play, review |
+| `ai-items` | Agents, skills, commands and prompts | install into `~/.claude`, update from a repository |
+
+## Builders
+
+A `cmd-*-project.sh` in a `sites` folder builds a project: Drupal (9 to 12), Drupal CMS, the Webship distributions. Each carries a `# workspace-name:` header the dashboard shows in its Build dropdown, declares its own distribution values, and runs everything through DDEV (`ddev config`, `ddev composer`, `ddev drush`), never against the host. Every build runs Node.js 24.
+
+## Commands
+
+Every `cmd-*.sh` finds the tooling from its own path (`core/scripts/bootstrap.sh`), so a fresh workspace needs no environment variables. Tools (`cmd-tools-*.sh`) act on an existing project: back it up, restore it, run its tests, link it to a host. A plugin's command is placed into the folders its manifest names, with `__WORKSPACE__` filled in.
+
+## Each folder is a plugin
+
+`@webship.co/workspace-dev`, `-test`, `-drupal-modules`, `-drupal-themes`, `-docs`, … carry the folder's settings template, commands and docs. `webship-workspace plugin require|activate|install <name>` adds one; the folder, its content and its settings stay when it is deactivated.

package/core/scripts/args/arg-ai-items.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('NAME',
+                    default='_all_',
+                    nargs='?',
+                    help='One item by name. Default: every item.')
+parser.add_argument('-s', '--status',
+                    action='store_true',
+                    default=False,
+                    help='Show what each source has: this workspace folder, ~/.claude, and the shared repo.')
+parser.add_argument('-l', '--list-remote',
+                    action='store_true',
+                    default=False,
+                    help='List what the shared repo (webship/ai-agents) has.')
+parser.add_argument('-o', '--source',
+                    default='repo',
+                    help='Where to read from: repo (webship/ai-agents) or claude (~/.claude). default [ repo ]')
+parser.add_argument('-t', '--filter',
+                    default='webship',
+                    help='With --source claude, only items whose name starts with this. _all_ for every item. default [ webship ]')
+parser.add_argument('-f', '--fetch',
+                    action='store_true',
+                    default=False,
+                    help='Fetch from the shared repo into ~/.claude, so a session can use it now.')
+parser.add_argument('-p', '--pull',
+                    action='store_true',
+                    default=False,
+                    help='Pull into this workspace folder from --source (repo by default, or claude).')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Install from this workspace folder into ~/.claude (your own draft).')
+parser.add_argument('-k', '--check',
+                    action='store_true',
+                    default=False,
+                    help='Compare what is installed against its source (repo or workspace draft), without changing anything.')
+parser.add_argument('-A', '--add',
+                    default='_none_',
+                    help='Install NAME (or every item) from any GitHub repo: owner/repo, owner/repo@ref, or a github.com URL (tree URLs pick a branch and folder). Combines with --to.')
+parser.add_argument('-U', '--update',
+                    action='store_true',
+                    default=False,
+                    help='Re-install every tracked item whose source moved (repo or workspace draft). Combines with --to.')
+parser.add_argument('-T', '--to',
+                    default='_none_',
+                    help='With --install, put it in one project instead of the global ~/.claude/: dev/myproject. Default: global.')
+parser.add_argument('-P', '--propose',
+                    action='store_true',
+                    default=False,
+                    help='Hand NAME to the AI agent to file the issue and open the PR on the shared repo. Prints the plan unless --confirm is added.')
+parser.add_argument('-m', '--summary',
+                    default='_none_',
+                    help='With --propose, what the item is for. Goes into the issue and the PR.')
+parser.add_argument('-C', '--confirm',
+                    action='store_true',
+                    default=False,
+                    help='With --propose, actually create the issue and the PR. Without it, only the plan is printed.')
+parser.add_argument('-c', '--clone-to',
+                    default='_none_',
+                    help='Copy NAME to this new name in this workspace folder, rewriting its identity, to customise it.')
+parser.add_argument('-u', '--purpose',
+                    default='_none_',
+                    help='With --clone-to, what the copy is for. Claude Code then tailors and reformats it for that purpose.')
+ARGEOF

package/core/scripts/args/arg-autostart.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('-e', '--enable',
+                    action='store_true',
+                    default=False,
+                    help='Install the systemd user service that starts the configured projects at boot, and turn on lingering so it runs without anyone logging in.')
+parser.add_argument('-d', '--disable',
+                    action='store_true',
+                    default=False,
+                    help='Stop and remove the boot service. The domain stays as it is; only the automatic start goes.')
+parser.add_argument('-o', '--domain',
+                    default="_none_",
+                    help='The one name the dashboard answers on, project and TLD together: workspace.ddev.site. The first label is the DDEV project name, the rest is the project TLD, and every workspace and project hostname follows from it.')
+parser.add_argument('-a', '--apply',
+                    action='store_true',
+                    default=False,
+                    help='Apply the domain from the settings file to DDEV now and restart, without changing what is configured.')
+parser.add_argument('-n', '--now',
+                    action='store_true',
+                    default=False,
+                    help='Start the configured projects immediately, exactly as the boot service would. Use it to prove the service will work before rebooting.')
+parser.add_argument('-R', '--restart-all',
+                    action='store_true',
+                    default=False,
+                    help='After a TLD change, restart every other running project so it answers on the new name too. Without this they are listed and left alone, because restarting a site mid-build is how a half-written database happens.')
+parser.add_argument('-f', '--force',
+                    action='store_true',
+                    default=False,
+                    help='Go ahead with a TLD that has no wildcard DNS, or with a project rename. Both are refused without this, and both break things in ways that are tedious to undo.')
+ARGEOF

package/core/scripts/args/arg-avatar-agent.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+import re
+
+def text(value):
+    # argparse-bash hands values to the shell through eval: refuse what the shell would expand.
+    if re.search(r'[\$\`"\\\\]', value):
+        raise argparse.ArgumentTypeError('may not contain quotes, dollar signs, backticks or backslashes')
+    return value
+
+parser.add_argument('PROJECT_NAME',
+                    nargs='?',
+                    default="_none_",
+                    help='The avatar project, e.g. my-avatar.')
+parser.add_argument('-a', '--action',
+                    choices=['list', 'link', 'create', 'check'],
+                    default='list',
+                    help='list the project agents and whether ~/.claude uses them (default); link them into ~/.claude; create an agent for a character; check Claude Code in the container.')
+parser.add_argument('-i', '--id',
+                    type=text,
+                    default="_none_",
+                    help='For create: the character the agent is the mind of (characters/<id>.json).')
+parser.add_argument('-R', '--replace',
+                    action='store_true',
+                    default=False,
+                    help='For create: write the agent file again even if it exists. For link: point links that use another project copy at this one.')
+ARGEOF

package/core/scripts/args/arg-avatar-catalog.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('-a', '--action',
+                    choices=['voices', 'avatars'],
+                    default='voices',
+                    help='voices: voice engines and their licences (default); avatars: avatar libraries and their licences.')
+parser.add_argument('-l', '--list',
+                    action='store_true',
+                    default=False,
+                    help='With avatars: also list every public VRM in the Open Source Avatars registry, with its licence.')
+ARGEOF

package/core/scripts/args/arg-avatar-character.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+import re
+
+def text(value):
+    # argparse-bash hands values to the shell through eval: refuse what the shell would expand.
+    if re.search(r'[\$\`"\\\\]', value):
+        raise argparse.ArgumentTypeError('may not contain quotes, dollar signs, backticks or backslashes')
+    return value
+
+parser.add_argument('PROJECT_NAME',
+                    nargs='?',
+                    default="_none_",
+                    help='The avatar project, e.g. my-avatar.')
+parser.add_argument('-a', '--action',
+                    choices=['list', 'add', 'remove'],
+                    default='list',
+                    help='list the characters (default), add one, or remove one (its file is moved aside, its model kept).')
+parser.add_argument('-i', '--id',
+                    type=text,
+                    default="_none_",
+                    help='The character id: lowercase letters, digits and hyphens, e.g. ada.')
+parser.add_argument('-n', '--name',
+                    type=text,
+                    default="_none_",
+                    help='The name it shows and answers to, e.g. Ada.')
+parser.add_argument('-m', '--model',
+                    type=text,
+                    default="_none_",
+                    help='Where its body comes from: an https URL to a .vrm, or osa:<name> from Open Source Avatars (bash cmd-tools-avatar-catalog.sh -a avatars --list). Downloaded into public/models/<id>.vrm.')
+parser.add_argument('-M', '--model-file',
+                    type=text,
+                    default="_none_",
+                    help='A model already in the project public/models/, e.g. my-character.vrm.')
+parser.add_argument('-e', '--voice-engine',
+                    choices=['browser', 'piper', 'elevenlabs'],
+                    default='_settings_',
+                    help='browser (free), piper (free, offline) or elevenlabs (spends credits). Default: avatar.voice_engine, piper.')
+parser.add_argument('-v', '--voice',
+                    type=text,
+                    default="_settings_",
+                    help='The voice: a Piper voice name (en_GB-alba-medium), an ElevenLabs voice id, or empty for the browser default. Default: avatar.voice, a free Piper voice.')
+parser.add_argument('-L', '--language',
+                    type=text,
+                    default='en-US',
+                    help='What it speaks by default, e.g. en-GB or ar-JO.')
+parser.add_argument('-g', '--gender',
+                    choices=['f', 'm'],
+                    default="_none_",
+                    help='Picks Arabic grammar for the page labels.')
+parser.add_argument('-c', '--credit',
+                    type=text,
+                    default="_none_",
+                    help='Who made the model and under which terms. Filled in from the registry for osa: models.')
+parser.add_argument('-p', '--persona-file',
+                    type=text,
+                    default="_none_",
+                    help='A text file with the persona: who the character is and how it speaks. Used when it has no agent.')
+parser.add_argument('-G', '--agent',
+                    type=text,
+                    default="_none_",
+                    help='A Claude Code agent in ~/.claude/agents/ to be its mind. Or create one: cmd-tools-avatar-agent.sh -a create.')
+parser.add_argument('-R', '--replace',
+                    action='store_true',
+                    default=False,
+                    help='Overwrite an existing characters/<id>.json.')
+ARGEOF

package/core/scripts/args/arg-avatar-voice.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+import re
+
+def text(value):
+    # argparse-bash hands values to the shell through eval: refuse what the shell would expand.
+    if re.search(r'[\$\`"\\\\]', value):
+        raise argparse.ArgumentTypeError('may not contain quotes, dollar signs, backticks or backslashes')
+    return value
+
+parser.add_argument('PROJECT_NAME',
+                    nargs='?',
+                    default="_none_",
+                    help='The avatar project, e.g. my-avatar. Not needed for piper-list and piper-install.')
+parser.add_argument('-a', '--action',
+                    choices=['status', 'piper-list', 'piper-install', 'elevenlabs-link', 'elevenlabs-unlink'],
+                    default='status',
+                    help='status of every engine (default); list or install free Piper voices; link or unlink the ElevenLabs key from settings.yml (never printed).')
+parser.add_argument('-v', '--voice',
+                    type=text,
+                    default="_none_",
+                    help='For piper-install: a Piper voice name, e.g. en_GB-alba-medium or ar_JO-kareem-medium.')
+ARGEOF

package/core/scripts/args/arg-avatar.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    nargs='?',
+                    default="_settings_",
+                    help='The name of the avatar project. It becomes https://<PROJECT_NAME>.ddev.site. Default: avatar.project from the workspace settings.')
+parser.add_argument('-r', '--repo',
+                    default="_settings_",
+                    help='The avatar app repository to clone. Default: avatar.repo from the workspace settings.')
+parser.add_argument('-b', '--branch',
+                    default="_settings_",
+                    help='The branch to clone. Default: avatar.branch.')
+parser.add_argument('-A', '--link-agents',
+                    action='store_true',
+                    default=False,
+                    help='Link the project Claude Code agents (claude/agents/*.md) into ~/.claude once it is up. They then point at THIS copy.')
+parser.add_argument('-l', '--launch',
+                    action='store_true',
+                    default=False,
+                    help='Open the avatar in a browser when it is ready.')
+ARGEOF

package/core/scripts/args/arg-checks.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The project, product, module, theme, recipe or library to check.')
+parser.add_argument('-l', '--list',
+                    action='store_true',
+                    default=False,
+                    help='Print the plan — every check, the script the package declares for it, the command it would run, the package manager and where it would run — and stop. Runs nothing and needs no dependencies, so it is the fastest way to see what a package actually covers.')
+parser.add_argument('-o', '--only',
+                    default="_none_",
+                    help='Run only these checks, comma separated. Ids: format, js, css, yaml, spelling, types, php, twig, e2e. Example: --only js,css')
+parser.add_argument('-s', '--skip',
+                    default="_none_",
+                    help='Skip these checks, comma separated. Applied after --only. Example: --skip spelling')
+parser.add_argument('-e', '--e2e',
+                    action='store_true',
+                    default=False,
+                    help='Include the browser suite. Off by default: it needs a running site to point a browser at, and it takes minutes. On a site this hands over to cmd-tools-testing.sh rather than reimplementing it.')
+parser.add_argument('-b', '--browser',
+                    default="chromium",
+                    choices=['chromium', 'firefox', 'webkit'],
+                    help='Which browser the e2e check asks for [default %(default)s].')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Install the package dependencies first when they are missing. Off by default because installing runs the package own postinstall and prepare scripts, and several packages here write into a docroot from theirs.')
+parser.add_argument('-r', '--runner',
+                    default="_none_",
+                    choices=['npm', 'yarn'],
+                    help='Force the package manager instead of reading packageManager and the lockfiles. Needed only where a package carries both lockfiles.')
+parser.add_argument('-F', '--fail-fast',
+                    action='store_true',
+                    default=False,
+                    help='Stop at the first failing check. By default every check runs and the command exits once at the end, so one failure does not hide the rest.')
+ARGEOF

package/core/scripts/args/arg-clone.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# Arguments for cloning a project — folder and database — into a new name,
+# here or in another workspace. Two shapes of clone, one command:
+#
+#   the default    a full independent copy (rsync + its own database)
+#   --worktree     a git worktree of the same repository, sharing one .git
+#
+# --worktree is only offered where it can work: the source has to be a git
+# checkout. Everything below it is worktree-only and says so, because a flag
+# that silently does nothing is worse than one that refuses.
+argparse "$@" <<EOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The project to clone (a folder in this workspace).')
+parser.add_argument('-t', '--to',
+                    default="_none_",
+                    help='The name of the clone. Required. Example: --to myproject-copy')
+parser.add_argument('-w', '--target-workspace',
+                    default="_none_",
+                    help='Clone into this workspace instead of the current one. Example: --target-workspace sandboxes')
+parser.add_argument('-g', '--worktree',
+                    action='store_true',
+                    help='Clone as a git worktree instead of copying the files: one shared .git, a branch per folder, its own DDEV project. Needs the source to be a git checkout.')
+parser.add_argument('-b', '--branch',
+                    default="_none_",
+                    help='Worktree only. The branch to check out; created from the current HEAD when it does not exist. Defaults to the clone name.')
+parser.add_argument('--no-build-copy',
+                    action='store_true',
+                    help='Worktree only. Do not copy the git-ignored build (vendor, contrib, files, settings) from the source — leaves you to run composer install yourself.')
+# --extra-hostname, not --hostname: argparse assigns the dest as a shell variable
+# and HOSTNAME is a bash builtin. Clobbering it inside a build script is the kind
+# of thing that is found much later, in something unrelated.
+parser.add_argument('-H', '--extra-hostname',
+                    default="_none_",
+                    help='Give the clone an extra address as well as its canonical one. A label, no dots: --extra-hostname staging becomes staging.ddev.site.')
+parser.add_argument('-W', '--with-workspace-hostname',
+                    action='store_true',
+                    help='Give the clone <name>-<workspace> as an extra address, so which workspace it lives in is visible in one flat hostname.')
+parser.add_argument('--no-db',
+                    action='store_true',
+                    help='Do not export and import the database. The clone starts with whatever an empty DDEV project has.')
+EOF

package/core/scripts/args/arg-commands.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('-l', '--list',
+                    action='store_true',
+                    default=False,
+                    help='List every cmd-*.sh in the workspace. This is also the default.')
+parser.add_argument('-w', '--workspace',
+                    default='_all_',
+                    help='Limit --list to one workspace, or say where --new and --clone put the copy. default [ _all_ ]')
+parser.add_argument('-r', '--list-remote',
+                    action='store_true',
+                    default=False,
+                    help='List what the tooling repository has, and whether this machine has it, the same, or different.')
+parser.add_argument('-p', '--pull',
+                    default='_none_',
+                    help='Bring one cmd-*.sh down from the tooling repository into the workspace folder it belongs to.')
+parser.add_argument('-d', '--diff',
+                    default='_none_',
+                    help='Show one cmd-*.sh on this machine against the copy in the tooling repository.')
+parser.add_argument('-c', '--clone',
+                    default='_none_',
+                    help='Copy an existing cmd-*.sh. Needs --to, and --workspace to retarget it elsewhere.')
+parser.add_argument('-t', '--to',
+                    default='_none_',
+                    help='With --clone, the new file name (cmd-<something>.sh).')
+parser.add_argument('-n', '--new',
+                    default='_none_',
+                    help='Scaffold a new cmd-*.sh with the bootstrap chain already correct. Needs --workspace.')
+parser.add_argument('-b', '--label',
+                    default='_none_',
+                    help="With --new, the '# workspace-name:' header — the human name the dashboard shows.")
+parser.add_argument('-S', '--sync',
+                    action='store_true',
+                    default=False,
+                    help='Bring every command down from the tooling repository. Reports what would change; --confirm takes the ones this machine is missing.')
+parser.add_argument('-O', '--overwrite',
+                    action='store_true',
+                    default=False,
+                    help='With --sync --confirm, also replace the commands that differ. Each one is kept under backups/ first.')
+parser.add_argument('-o', '--propose',
+                    default='_none_',
+                    help='Hand one cmd-*.sh to the AI agent to file the issue and open the PR on the tooling repository.')
+parser.add_argument('-s', '--summary',
+                    default='_none_',
+                    help='With --propose, what the command is for. Goes into the issue and the PR.')
+parser.add_argument('-y', '--confirm',
+                    action='store_true',
+                    default=False,
+                    help='With --propose, actually create the issue and the PR. Without it, only the plan is printed.')
+ARGEOF

package/core/scripts/args/arg-cucumber.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<EOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project.')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Add the install flag to install the project.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='Add default set of users to the project in the case of install')
+parser.add_argument('-r', '--require',
+                    default="_none_",
+                    nargs='+',
+                    help='Require more modules/themes/libraries by composer. Example: --require "drupal/ctools:~3.0 drupal/token:~1.0"')
+parser.add_argument('-e', '--enable',
+                    default="_none_",
+                    nargs='+',
+                    help='Enable modules right after the install. Example: --enable "media media_library ctools token"')
+parser.add_argument('-s', '--skip-set-default-settings',
+                    action='store_true',
+                    default=False,
+                    help='Skip set default settings file before starting the install')
+parser.add_argument('-d', '--skip-drop-database',
+                    action='store_true',
+                    default=False,
+                    help='Skip drop the database and create it again before starting the install')
+parser.add_argument('-p', '--php-version',
+                    default="",
+                    choices=['8.5', '8.4', '8.3', '8.2', '8.1', '8.0', '7.4'],
+                    help='PHP version for the project container. The seven most recent PHP releases DDEV supports; empty means the builder default. Example: --php-version 8.3')
+EOF

package/core/scripts/args/arg-distribution.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<EOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project.')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Add the install flag to install the project.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='Add default set of users to the project in the case of install')
+parser.add_argument('-r', '--require',
+                    default="_none_",
+                    nargs='+',
+                    help='Require more modules/themes/libraries by composer. Example: --require "drupal/ctools:~3.0 drupal/token:~1.0"')
+parser.add_argument('-e', '--enable',
+                    default="_none_",
+                    nargs='+',
+                    help='Enable modules right after the install. Example: --enable "media media_library ctools token"')
+parser.add_argument('-s', '--skip-set-default-settings',
+                    action='store_true',
+                    default=False,
+                    help='Skip set default settings file before starting the install')
+parser.add_argument('-d', '--skip-drop-database',
+                    action='store_true',
+                    default=False,
+                    help='Skip drop the database and create it again before starting the install')
+EOF

package/core/scripts/args/arg-drupal.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<EOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project.')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Add the install flag to install the project.')
+parser.add_argument('-l', '--launch',
+                    action='store_true',
+                    default=False,
+                    help='Open the site in a browser when it is ready.')
+parser.add_argument('-d', '--dev',
+                    action='store_true',
+                    default=False,
+                    help='Build the development branch instead of the latest release.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='Add default set of users to the project in the case of install')
+parser.add_argument('-p', '--profile',
+                    default="standard",
+                    nargs='+',
+                    choices=['standard', 'minimal', 'umami'],
+                    help='Select which Drupal profile to install [default %(default)s]. Example: --profile minimal')
+parser.add_argument('-r', '--require',
+                    default="_none_",
+                    nargs='+',
+                    help='Require more modules/themes/libraries by composer. Example: --require "drupal/ctools:~3.0 drupal/token:~1.0"')
+parser.add_argument('-e', '--enable',
+                    default="_none_",
+                    nargs='+',
+                    help='Enable modules right after the install. Example: --enable "media media_library ctools token"')
+parser.add_argument('--php-version',
+                    default="",
+                    choices=['8.5', '8.4', '8.3', '8.2', '8.1', '8.0', '7.4'],
+                    help='PHP version for the project container. The seven most recent PHP releases DDEV supports; empty means the builder default, and DDEV\'s own default under that. Example: --php-version 8.3')
+EOF

package/core/scripts/args/arg-drupal_cms.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<EOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project.')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Add the install flag to install the project.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='Add default set of users to the project in the case of install')
+parser.add_argument('--php-version',
+                    default="",
+                    choices=['8.5', '8.4', '8.3', '8.2', '8.1', '8.0', '7.4'],
+                    help='PHP version for the project container. The seven most recent PHP releases DDEV supports; empty means the builder default. Example: --php-version 8.3')
+EOF

package/core/scripts/args/arg-gitlab-ci-local.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The project directory in this workspace (a git clone with a .gitlab-ci.yml).')
+parser.add_argument('JOB',
+                    default='_none_',
+                    nargs='?',
+                    help='One job to run by name. Default: the whole pipeline.')
+parser.add_argument('-l', '--list',
+                    action='store_true',
+                    default=False,
+                    help='List the jobs and their stages instead of running.')
+parser.add_argument('-s', '--slim',
+                    action='store_true',
+                    default=False,
+                    help='Run the project\'s committed .gitlab-ci-local.yml (the reproducible subset) instead of the full pipeline.')
+parser.add_argument('-v', '--variable',
+                    default="_none_",
+                    help='Pass one variable through, e.g. --variable DRUPAL_CORE=11.4.0')
+parser.add_argument('-d', '--doctor',
+                    action='store_true',
+                    default=False,
+                    help='Only check the setup: gitlab-ci-local, the drupal-ci-local wrapper, Docker, SSH to git.drupal.org.')
+ARGEOF

package/core/scripts/args/arg-graphify.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project to map.')
+parser.add_argument('-q', '--query',
+                    default="",
+                    help='Ask the existing graph a question instead of rebuilding it. Example: --query "what does this controller depend on?"')
+parser.add_argument('-d', '--deep',
+                    action='store_true',
+                    default=False,
+                    help='Add the semantic pass over docs, PDFs and images. Needs an LLM backend and sends file contents to it. It does not link Drupal YAML to PHP classes.')
+parser.add_argument('-f', '--force',
+                    action='store_true',
+                    default=False,
+                    help='Skip the incremental manifest gate and the semantic cache. Unchanged files are still replayed from graphify-out/cache/ast — delete that directory for a true re-parse.')
+parser.add_argument('-S', '--scope',
+                    default="contrib",
+                    choices=['custom', 'contrib', 'all'],
+                    help='How much of the tree to map: custom code only, custom + contrib modules/themes/profiles, or everything including core and vendor [default %(default)s].')
+parser.add_argument('-a', '--all',
+                    action='store_true',
+                    default=False,
+                    help='Same as --scope all: do not skip vendor/, core/, contrib or libraries. Slow, and the graph ends up dominated by third-party code.')
+parser.add_argument('-Y', '--no-yaml',
+                    action='store_true',
+                    default=False,
+                    help='Do not mirror the YAML as JSON. graphify parses no YAML of its own, so on a recipe or a config-heavy module this leaves the graph empty.')
+parser.add_argument('-s', '--store',
+                    default='_none_',
+                    help='Fetch a URL into the project\'s ./raw and fold it into the graph, so the AI can read it later. Example: --store https://www.drupal.org/node/3586390')
+parser.add_argument('-x', '--exclude',
+                    default="_none_",
+                    nargs='+',
+                    help='Extra paths to skip, on top of the defaults. Example: --exclude "web/modules/custom/legacy tests"')
+ARGEOF