openclaw - 💡(How to fix) Fix Scripts: Organize 150+ files in scripts/ directory by function with README index [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#59728Fetched 2026-04-08 02:41:20
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
Participants

Code Example

scripts/
├── analyze-plugin-sdk-usage.ts
├── audit-seams.mjs
├── auth-monitor.sh
├── bench-cli-startup.ts
├── build-and-run-mac.sh
├── bundle-a2ui.sh
├── canvas-a2ui-copy.ts
├── check-architecture-smells.mjs
├── check-channel-agnostic-boundaries.mjs
├── check-cli-startup-memory.mjs
├── check-no-conflict-markers.mjs
├── check-no-extension-src-imports.ts
├── check-no-extension-test-core-imports.ts
├── check-no-monolithic-plugin-sdk-entry-imports.ts
├── check-no-pairing-store-group-auth.mjs
├── check-no-random-messaging-tmp.mjs
├── check-no-raw-channel-fetch.mjs
├── check-no-raw-window-open.mjs
├── check-no-register-http-handler.mjs
├── check-pairing-account-scope.mjs
├── check-plugin-extension-import-boundary.mjs
├── check-plugin-sdk-exports.mjs
├── check-plugin-sdk-subpath-exports.mjs
├── check-ts-max-loc.ts
├── check-web-search-provider-boundaries.mjs
├── check-webhook-auth-body-order.mjs
├── ci-changed-scope.mjs
├── ci-write-manifest-outputs.mjs
├── clawlog.sh
├── docs-link-audit.mjs
├── docs-list.js
├── docs-spellcheck.sh
├── e2e/
│   └── ...
└── ... (100+ more files)

---

scripts/
├── README.md                    # Index of all scripts with descriptions
├── ci/                          # CI-specific orchestration
│   ├── changed-scope.mjs       # (was ci-changed-scope.mjs)
│   ├── manifest-outputs.mjs     # (was ci-write-manifest-outputs.mjs)
│   └── README.md
├── dev/                         # Local development helpers
│   ├── run-node.mjs            # (was run-node.mjs)
│   ├── watch-node.mjs          # (was watch-node.mjs)
│   ├── restart-mac.sh          # (was restart-mac.sh)
│   └── README.md
├── build/                       # Build pipeline steps
│   ├── tsdown-build.mjs        # (was tsdown-build.mjs)
│   ├── runtime-postbuild.mjs   # (was runtime-postbuild.mjs)
│   ├── bundle-a2ui.sh          # (was bundle-a2ui.sh)
│   └── README.md
├── release/                     # Release automation
│   ├── openclaw-npm-release-check.ts
│   ├── plugin-npm-release-plan.ts
│   └── README.md
├── analyze/                     # Code quality/auditing
│   ├── audit-seams.mjs         # (was audit-seams.mjs)
│   ├── check-ts-max-loc.ts     # (was check-ts-max-loc.ts)
│   ├── plugin-sdk-usage.ts     # (was analyze-plugin-sdk-usage.ts)
│   └── README.md
├── lib/                         # Shared script utilities
│   ├── arg-utils.mjs           # (was lib/arg-utils.mjs)
│   ├── vitest-report-cli-utils.mjs
│   └── test-report-utils.mjs
└── deprecated/                  # Old scripts (delete after 90 days)

---

# Scripts

## Quick Reference

| Script | Purpose | Directory |
|--------|---------|-----------|
| `pnpm run build` | Full production build | `build/` |
| `pnpm run dev` | Development with watch mode | `dev/` |
| `pnpm run test` | Run all tests | `ci/` |

## Directories

### `ci/`CI/CD Orchestration
Scripts that run in GitHub Actions or prepare CI artifacts.

### `dev/`Local Development
Scripts for everyday development tasks.

### `build/`Build Pipeline
Individual build steps (not usually run directly).

### `release/`Release Automation
Version bumping, changelog generation, publishing.

### `analyze/`Code Quality
Linting, auditing, and analysis scripts.

### `lib/`Shared Utilities
Internal utilities imported by other scripts.
RAW_BUFFERClick to expand / collapse

Problem

The scripts/ directory contains 150+ files with mixed extensions (.mjs, .ts, .sh) and no clear taxonomy. Names follow patterns like check-*.mjs, ci-*.mjs, test-*.mjs but aren't grouped by purpose, making discovery difficult.

Current State

scripts/
├── analyze-plugin-sdk-usage.ts
├── audit-seams.mjs
├── auth-monitor.sh
├── bench-cli-startup.ts
├── build-and-run-mac.sh
├── bundle-a2ui.sh
├── canvas-a2ui-copy.ts
├── check-architecture-smells.mjs
├── check-channel-agnostic-boundaries.mjs
├── check-cli-startup-memory.mjs
├── check-no-conflict-markers.mjs
├── check-no-extension-src-imports.ts
├── check-no-extension-test-core-imports.ts
├── check-no-monolithic-plugin-sdk-entry-imports.ts
├── check-no-pairing-store-group-auth.mjs
├── check-no-random-messaging-tmp.mjs
├── check-no-raw-channel-fetch.mjs
├── check-no-raw-window-open.mjs
├── check-no-register-http-handler.mjs
├── check-pairing-account-scope.mjs
├── check-plugin-extension-import-boundary.mjs
├── check-plugin-sdk-exports.mjs
├── check-plugin-sdk-subpath-exports.mjs
├── check-ts-max-loc.ts
├── check-web-search-provider-boundaries.mjs
├── check-webhook-auth-body-order.mjs
├── ci-changed-scope.mjs
├── ci-write-manifest-outputs.mjs
├── clawlog.sh
├── docs-link-audit.mjs
├── docs-list.js
├── docs-spellcheck.sh
├── e2e/
│   └── ...
└── ... (100+ more files)

Issues

  1. Discovery — New contributors can't find existing scripts
  2. Duplication risk — Similar functionality may exist but be hard to locate
  3. No ownership — Unclear who maintains which scripts
  4. Mixed extensions — Inconsistent .mjs, .ts, .sh usage

Proposed Structure

scripts/
├── README.md                    # Index of all scripts with descriptions
├── ci/                          # CI-specific orchestration
│   ├── changed-scope.mjs       # (was ci-changed-scope.mjs)
│   ├── manifest-outputs.mjs     # (was ci-write-manifest-outputs.mjs)
│   └── README.md
├── dev/                         # Local development helpers
│   ├── run-node.mjs            # (was run-node.mjs)
│   ├── watch-node.mjs          # (was watch-node.mjs)
│   ├── restart-mac.sh          # (was restart-mac.sh)
│   └── README.md
├── build/                       # Build pipeline steps
│   ├── tsdown-build.mjs        # (was tsdown-build.mjs)
│   ├── runtime-postbuild.mjs   # (was runtime-postbuild.mjs)
│   ├── bundle-a2ui.sh          # (was bundle-a2ui.sh)
│   └── README.md
├── release/                     # Release automation
│   ├── openclaw-npm-release-check.ts
│   ├── plugin-npm-release-plan.ts
│   └── README.md
├── analyze/                     # Code quality/auditing
│   ├── audit-seams.mjs         # (was audit-seams.mjs)
│   ├── check-ts-max-loc.ts     # (was check-ts-max-loc.ts)
│   ├── plugin-sdk-usage.ts     # (was analyze-plugin-sdk-usage.ts)
│   └── README.md
├── lib/                         # Shared script utilities
│   ├── arg-utils.mjs           # (was lib/arg-utils.mjs)
│   ├── vitest-report-cli-utils.mjs
│   └── test-report-utils.mjs
└── deprecated/                  # Old scripts (delete after 90 days)

Migration Plan

Phase 1: Organize (No Code Changes)

  1. Create new directory structure
  2. Move scripts to appropriate directories
  3. Update relative imports in moved files
  4. Update package.json script references
  5. Update CI workflow references

Phase 2: Add Documentation

  1. Create scripts/README.md with index:
# Scripts

## Quick Reference

| Script | Purpose | Directory |
|--------|---------|-----------|
| `pnpm run build` | Full production build | `build/` |
| `pnpm run dev` | Development with watch mode | `dev/` |
| `pnpm run test` | Run all tests | `ci/` |

## Directories

### `ci/` — CI/CD Orchestration
Scripts that run in GitHub Actions or prepare CI artifacts.

### `dev/` — Local Development
Scripts for everyday development tasks.

### `build/` — Build Pipeline
Individual build steps (not usually run directly).

### `release/` — Release Automation
Version bumping, changelog generation, publishing.

### `analyze/` — Code Quality
Linting, auditing, and analysis scripts.

### `lib/` — Shared Utilities
Internal utilities imported by other scripts.

Phase 3: Extension Standardization (Optional)

  • Migrate remaining .mjs to .ts where appropriate
  • Document extension choice rationale

Acceptance Criteria

  • All scripts organized into categorized directories
  • scripts/README.md with complete index
  • Each subdirectory has its own README
  • No scripts remain in root scripts/ directory
  • All package.json references updated
  • All CI workflow references updated
  • CI passes with new structure

References

  • Current scripts: scripts/ (150+ files)
  • Related: package.json scripts section

Priority: High Effort: Low (1-2 days) Labels: dx, refactor, good first issue

extent analysis

TL;DR

Organize scripts into categorized directories and update references to improve discoverability and maintainability.

Guidance

  1. Create a new directory structure: Implement the proposed structure with categories like ci/, dev/, build/, release/, analyze/, and lib/.
  2. Move scripts to appropriate directories: Update the location of each script based on its purpose, and ensure that all scripts are moved out of the root scripts/ directory.
  3. Update relative imports and references: Modify package.json and CI workflow references to point to the new script locations, and update any relative imports within the scripts themselves.
  4. Document the script index: Create a scripts/README.md file with a complete index of all scripts, including their purposes and directories, to facilitate discovery and understanding.

Example

The scripts/README.md index might include a table like the one proposed in the migration plan, listing each script, its purpose, and its directory:

| Script | Purpose | Directory |
|--------|---------|-----------|
| `pnpm run build` | Full production build | `build/` |
| `pnpm run dev` | Development with watch mode | `dev/` |
| `pnpm run test` | Run all tests | `ci/` |

Notes

This reorganization should improve the discoverability of scripts and reduce the risk of duplication. However, it may require additional effort to standardize file extensions and document the rationale behind extension choices.

Recommendation

Apply the proposed directory structure and update references to improve script organization and discoverability, as this will address the primary issues of discovery, duplication risk, and unclear ownership.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix Scripts: Organize 150+ files in scripts/ directory by function with README index [1 participants]