Skip to Content
Code Wikiscripts

scripts

Scripts Module

The scripts directory contains utility scripts for the cfxdevkit monorepo. These scripts automate development, maintenance, and release tasks. Each script is self-contained and executable from the repository root.

fix-kebab-groups.mjs

Resolves kebab-group violations by moving files into prefixed subdirectories and updating import references.

Process

  1. Reads artifacts/llm/reports/kebab-groups.json (generated by pnpm run check:kebab-groups)
  2. For each file group sharing a directory prefix:
    • Creates subdirectory named after the prefix
    • Moves files into the subdirectory, stripping the prefix from filenames
    • Processes longest prefixes first to handle nesting
  3. In dry-run mode (--dry-run), logs proposed moves
  4. Otherwise, executes moves via git mv (creating directories as needed)
  5. Builds import replacement map (old specifier → new specifier without extension)
  6. Scans source files (excluding node_modules, .git, dist, artifacts) for:
    • .ts, .tsx, .js, .jsx, .json, .md, .mdx, .yml, .yaml, .css
  7. Updates import/require statements using regex to match quoted specifiers
  8. Reports moved files and files with updated imports

Usage

node scripts/fix-kebab-groups.mjs        # Execute moves
node scripts/fix-kebab-groups.mjs --dry-run  # Preview changes

fix-kebab-imports.mjs

Updates import paths after kebab-group file moves, handling both relocated imports and depth-adjusted imports in moved files.

Process

  1. Reads kebab-groups.json report
  2. Builds two maps:
    • moveMap: old file paths (without extension) → new file paths (without extension)
    • depthShiftMap: new file paths → directory depth increase (for adjusting relative imports)
  3. Scans source files (same exclusions as fix-kebab-groups)
  4. For each import/require statement:
    • Attempts to resolve specifier against moveMap (trying extensions/index files)
    • If found, replaces with new relative path
    • If current file was moved and specifier not in moveMap:
      • Adjusts by prepending ../ for each depth level increase
  5. Reports files modified and total import changes

Usage

node scripts/fix-kebab-imports.mjs        # Execute fixes
node scripts/fix-kebab-imports.mjs --dry-run  # Preview changes

publish-packages.mjs

Publishes non-private, non-ignored workspace packages to npm.

Process

  1. Reads .changeset/config.json for ignored packages (if any)
  2. Discovers packages under repos/*/packages/ (only cfx-* repos) with package.json
  3. For each package:
    • Skips if private, nameless, or in ignore list
    • Checks if version already published via npm view (skips if published and not dry-run)
    • Packs package with pnpm pack (output to repository root)
    • Publishes tarball via npm publish --access public --provenance
    • Removes tarball after publish
  4. Handles dry-run mode (--dry-run) to simulate without publishing

Key Functions

  • run(): Wrapper for spawnSync that throws on non-zero exit
  • readJson(): Parses JSON files
  • collectPackageDirs(): Returns sorted package directory paths
  • packageExists(): Checks npm for existing package version

Usage

node scripts/publish-packages.mjs        # Publish packages
node scripts/publish-packages.mjs --dry-run  # Simulate publish

scaffold-empty-packages.sh

Idempotently scaffolds standard package structure for new workspace packages.

Process

  1. Defines write_if_missing: creates file only if absent
  2. Defines scaffold_lib: generates package structure for given:
    • Directory path
    • Package name
    • Description
    • Type (node or react)
  3. Structure includes:
    • package.json: name, version, scripts, devDependencies (Vite, Vitest, etc.)
    • tsconfig.json: extends @cfxdevkit/tsconfig/lib.json
    • vite.config.ts: library build config with optional React externals
    • vitest.config.ts: basic test configuration
    • src/index.ts: placeholder export
    • src/index.test.ts: smoke test
    • moon.yml: Moonrepo project configuration
  4. Invokes scaffold_lib for predefined packages (framework, domains, platform)

Usage

bash scripts/scaffold-empty-packages.sh

setup-trust-local-ca.sh

Installs mkcert root CA on host to trust *.dev.cfxdevkit.org certificates.

Process (run on host machine after devcontainer creation)

  1. Detects container engine (docker/podman) and finds running devcontainer
  2. Copies rootCA.pem (and rootCA-key.pem if present) from container to host temp dir
  3. Installs mkcert on host if missing (via brew/apt/dnf)
  4. Sets CAROOT to temp dir and runs mkcert -install
  5. Optionally imports CA into NSS databases for Firefox/system trust
  6. Outputs instructions to restart browser and verify https://showcase.dev.cfxdevkit.org

Usage

bash scripts/setup-trust-local-ca.sh

showcase-dev.sh

Starts the showcase application (local and public variants) on ports 3010/3011.

Process

  1. Checks for existing listeners on ports 3010/3011
  2. If found, verifies they are showcase processes (by checking parent process args)
  3. If showcase already running, exits with message
  4. If port conflict (non-showcase listener), exits with error
  5. Otherwise, runs: 
    pnpm --parallel --filter @cfxdevkit/example-showcase-local --filter @cfxdevkit/example-showcase-public dev

Usage

bash scripts/showcase-dev.sh

stop-showcase.sh

Stops showcase application listeners on ports 3010/3011.

Process

  1. Uses ss to find PIDs listening on ports 3010/3011
  2. Kills identified processes
  3. Reports action taken or absence of listeners

Usage

bash scripts/stop-showcase.sh

validate-repos.mjs

Validates all cfx-* repositories by running workspace and dependency checks.

Process

  1. Defines repository list: cfx-config, cfx-core, cfx-domain, cfx-keys, cfx-llm, cfx-meta, cfx-solidity, cfx-tools, cfx-ui
  2. Defines scripts to run per repo: validate-workspace.mjs, check-deps.mjs
  3. For each repo and script:
    • Constructs path to repos/<repo>/scripts/<script>
    • If script exists, runs via node (inherit stdio, NO_COLOR=1)
    • Records failures (non-zero exit)
  4. After all repos:
    • If failures exist, lists them and exits with code 1
    • Otherwise, reports success for all repos

Usage

node scripts/validate-repos.mjs

wire-package-dependencies.sh

Adds internal workspace dependencies according to API contracts using pnpm.

Process

  1. Defines add_dep: adds dependencies to packages matching filter
    • --save-prod for production deps
    • --save-peer for peer deps
  2. Applies predefined dependency wiring:
    • framework:
      • services → cdk
      • wallet → cdk, services
      • compiler → cdk
      • devnode → cdk
      • contracts → cdk
      • protocol → cdk
      • executor → cdk
      • react → cdk (prod), wallet (peer)
      • wallet-connect → cdk (prod), wallet (peer)
      • defi-react → cdk, services, react, wallet-connect (prod), theme (peer)
      • testing → cdk, devnode, contracts
    • domains:
      • game-engine → cdk, contracts
      • automation → cdk, services, wallet, executor, contracts
    • platform:
      • mcp-server → cdk, services, wallet, contracts, compiler, devnode
    • scaffold-cli: no internal deps

Usage

bash scripts/wire-package-dependencies.sh
Last updated on
Root