Skip to content

Unify fork management under forks/ directory#22

Merged
phroi merged 3 commits intomasterfrom
refactor/unify-forks-directory
Feb 25, 2026
Merged

Unify fork management under forks/ directory#22
phroi merged 3 commits intomasterfrom
refactor/unify-forks-directory

Conversation

@phroi
Copy link
Member

@phroi phroi commented Feb 25, 2026

Why

The fork tooling was scattered across three separate directories (ccc-fork/, fork-scripts/, reference/) with inconsistent conventions. This consolidates everything into a single forks/ directory where forker manages itself as a fork entry.

Changes

  • Structural refactor: Consolidate ccc-fork/, fork-scripts/, and reference/ into forks/ with a unified config.json. Forker becomes a self-managed fork entry. Pin files moved to forks/.pin/. All workspace refs updated from @ccc-fork/ to @forks/
  • Docs: Rewrite AGENTS.md fork section, update README.md, and replace all old paths throughout .planning/ docs
  • Fixes: Correct typo in dao.ts error message, fix BigInt comparison bug in sdk.ts (00n), fix typo in utils.ts doc comment

Consolidate ccc-fork/, fork-scripts/, and reference/ into a single
forks/ directory with forker as a self-managed fork entry. Pin files
now include resolution fingerprints for deterministic reuse across
re-records.

- Move ccc-fork/pins/ → forks/.pin/ccc/, config → forks/config.json
- Replace fork-scripts/ with forker (a fork entry managing itself)
- Absorb reference/ repos as clone-only entries in forks/config.json
- Move tsgo-filter.sh to repo root (no longer fork-scripts/ specific)
- Update .pnpmfile.cjs to scan forks/config.json instead of *-fork/
- Update all workspace package.json refs from @ccc-fork/ to @forks/
Rewrite AGENTS.md fork management section, update README.md, and
replace all ccc-fork/, fork-scripts/, reference/ paths throughout
.planning/ docs to reflect the unified forks/ structure.
- dao.ts: "have" → "has" in error message
- sdk.ts: compare against 0n instead of 0 for BigInt value
- utils.ts: "or" → "of" in doc comment
@gemini-code-assist
Copy link

Summary of Changes

Hello @phroi, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the project's fork management system by centralizing all related tooling and configurations into a new forks/ directory. This change streamlines the process of managing external repository forks, such as the CCC framework and reference contracts, by providing a unified configuration and automated setup. The refactor improves consistency, simplifies development workflows, and enhances maintainability by consolidating scattered scripts and configurations. Additionally, it includes minor bug fixes and documentation updates to reflect these structural changes.

Highlights

  • Structural Refactor: Consolidated ccc-fork/, fork-scripts/, and reference/ directories into a single forks/ directory, unifying fork management under a new forks/config.json. The forker tool now manages itself as a fork entry, and pin files have been relocated to forks/.pin/. All internal workspace references have been updated from @ccc-fork/ to @forks/.
  • Documentation Updates: Rewrote the fork management section in AGENTS.md, updated README.md with new fork development instructions, and replaced all old directory paths throughout the .planning/ documentation.
  • Bug Fixes and Typo Corrections: Corrected a typo in an error message within dao.ts, fixed a BigInt comparison bug in sdk.ts by changing 0 to 0n, and resolved a typo in a doc comment in utils.ts.
Changelog
  • .changeset/generalize-fork-management.md
    • Removed the changeset file as its purpose has been fulfilled by this PR.
  • .devcontainer/devcontainer.json
    • Updated the focus-timer git clone command to use --depth 1 for shallow cloning.
  • .planning/PROJECT.md
    • Updated references to local CCC dev build paths from ccc-fork/ to forks/ccc/ and fork-scripts/patch.sh to forks/forker/patch.sh.
  • .planning/REQUIREMENTS.md
    • Updated the reference for DAO check contribution from ccc-fork/ to forks/ccc/.
  • .planning/ROADMAP.md
    • Updated the reference for the DAO 64-output limit check from ccc-fork/ to forks/ccc/.
  • .planning/STATE.md
    • Updated references for DAO 64-output limit check and local patch mechanism from ccc-fork/ to forks/ccc/.
  • .planning/codebase/ARCHITECTURE.md
    • Updated references for on-chain contracts and the CCC framework location from reference/ and ccc-fork/ccc/ to forks/contracts/ and forks/ccc/ respectively.
  • .planning/codebase/CONCERNS.md
    • Updated references within discussions about local UDT handling and fragile CCC local override mechanisms from ccc-fork/ccc/ and fork-scripts/ to forks/ccc/ and forks/forker/.
  • .planning/codebase/CONVENTIONS.md
    • Updated references for local CCC override mechanism and Molecule schema path from fork-scripts/record.sh and reference/contracts/ to bash forks/forker/record.sh and forks/contracts/.
  • .planning/codebase/INTEGRATIONS.md
    • Updated references for smart contract sources and Molecule schema from reference/ to forks/.
  • .planning/codebase/STACK.md
    • Updated references for on-chain contracts, bash scripts, and pnpm workspace generation from reference/ and fork-scripts/ to forks/. Also updated the generated workspace markers.
  • .planning/codebase/STRUCTURE.md
    • Removed fork-scripts/, ccc-fork/, and reference/ directories from the project structure documentation.
    • Added a new forks/ directory to the project structure, detailing its unified configuration, pin storage (.pin/), self-hosting forker tool, and clones for CCC, contracts, and whitepaper.
    • Removed the scripts/ directory from the project structure documentation.
  • .planning/codebase/TESTING.md
    • Updated references for contract-alignment test targets from reference/contracts/ to forks/contracts/.
  • .planning/phases/01-ickb-utils-smarttransaction-removal/01-01-PLAN.md
    • Updated file paths and references from ccc-fork/ to forks/ within the plan for building DAO output limit checks.
  • .planning/phases/01-ickb-utils-smarttransaction-removal/01-01-SUMMARY.md
    • Updated references for local patch mechanisms and modified files from ccc-fork/ to forks/.
  • .planning/phases/01-ickb-utils-smarttransaction-removal/01-CONTEXT.md
    • Updated references for CCC DAO contribution development from ccc-fork/ to forks/ccc/.
  • .planning/phases/01-ickb-utils-smarttransaction-removal/01-RESEARCH.md
    • Updated references for DAO limit checks and local CCC development from ccc-fork/ to forks/ccc/.
  • .planning/phases/01-ickb-utils-smarttransaction-removal/01-VERIFICATION.md
    • Updated references for DAO limit check artifacts and local patches from ccc-fork/ to forks/ccc/.
  • .planning/phases/02-ccc-utility-adoption/02-RESEARCH.md
    • Updated references for CCC core barrel verification and code examples from ccc-fork/ccc/ to forks/ccc/.
  • .planning/phases/03-ccc-udt-integration-investigation/03-01-INVESTIGATION.md
    • Updated all file paths and references within the CCC Udt method chain trace from ccc-fork/ccc/ to forks/ccc/.
  • .planning/phases/03-ccc-udt-integration-investigation/03-01-PLAN.md
    • Updated key link paths and source file references from ccc-fork/ccc/ to forks/ccc/.
  • .planning/phases/03-ccc-udt-integration-investigation/03-CONTEXT.md
    • Updated references for PR #328 integration and FeePayer availability from ccc-fork/ccc/ to forks/ccc/.
  • .planning/phases/03-ccc-udt-integration-investigation/03-DECISION.md
    • Updated references for infoFrom implementation and xUDT cell identification from ccc-fork/ccc/ to forks/ccc/.
  • .planning/phases/03-ccc-udt-integration-investigation/03-RESEARCH.md
    • Updated references for PR #328 integration, Udt.infoFrom implementation, and FeePayer signature from ccc-fork/ccc/ to forks/ccc/.
  • .planning/research/ARCHITECTURE.md
    • Updated references for CCC UDT and Transaction class source code from ccc-fork/ccc/ to forks/ccc/.
  • .planning/research/FEATURES.md
    • Updated references for local CCC build usage from ccc-fork/ to forks/ccc/.
  • .planning/research/PITFALLS.md
    • Updated references for Molecule schema and local CCC utility functions from reference/contracts/ and ccc-fork/ to forks/.
  • .planning/research/STACK.md
    • Updated references for local CCC source code, UDT package, and PR #328 integration from ccc-fork/ccc/ to forks/ccc/.
  • .planning/research/SUMMARY.md
    • Updated references for local CCC build system and primary source for stack confidence from ccc-fork/ to forks/ccc/.
  • .pnpmfile.cjs
    • Refactored the auto-replay logic to handle a unified forks/config.json and bootstrap the forker tool.
    • Updated paths for fork directories and pin files to align with the new forks/ structure.
    • Modified the readPackage hook to correctly discover and override local fork packages based on the new configuration.
  • AGENTS.md
    • Removed the detailed 'Fork Management' and 'Reference Repos' sections.
    • Updated the 'Meta' section with a new 'Learn' note and added a 'Knowledge' section with general fork management instructions.
    • Updated the 'PR Workflow' to include pnpm changeset and a new clipboard usage example.
  • README.md
    • Updated instructions for developing with forks, including new paths and commands for forks/.pin/ and forks/forker/replay.sh.
    • Removed the 'Reference' section, as reference repos are now managed under forks/.
    • Updated developer script commands to reflect the new forks/forker/ structure.
  • apps/faucet/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • apps/interface/README.md
    • Corrected the path in the installation instructions from stack/app/interface to stack/apps/interface.
  • apps/interface/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • apps/interface/vite.config.ts
    • Updated the logic to detect fork source presence based on the new forks/ directory structure and configuration, changing the exclusion pattern for Babel.
  • apps/sampler/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • ccc-fork/.gitignore
    • Removed the .gitignore file from the old ccc-fork/ directory.
  • ccc-fork/README.md
    • Removed the README.md file from the old ccc-fork/ directory.
  • ccc-fork/config.json
    • Removed the config.json file from the old ccc-fork/ directory, as configuration is now unified under forks/config.json.
  • fork-scripts/clean-all.sh
    • Removed the clean-all.sh script from fork-scripts/.
  • fork-scripts/clean.sh
    • Removed the clean.sh script from fork-scripts/.
  • fork-scripts/lib.sh
    • Removed the lib.sh script from fork-scripts/.
  • fork-scripts/patch.sh
    • Removed the patch.sh script from fork-scripts/.
  • fork-scripts/push.sh
    • Removed the push.sh script from fork-scripts/.
  • fork-scripts/record.sh
    • Removed the record.sh script from fork-scripts/.
  • fork-scripts/replay-all.sh
    • Removed the replay-all.sh script from fork-scripts/.
  • fork-scripts/replay.sh
    • Removed the replay.sh script from fork-scripts/.
  • fork-scripts/reset.sh
    • Removed the reset.sh script from fork-scripts/.
  • fork-scripts/save.sh
    • Removed the save.sh script from fork-scripts/.
  • fork-scripts/status-all.sh
    • Removed the status-all.sh script from fork-scripts/.
  • fork-scripts/status.sh
    • Removed the status.sh script from fork-scripts/.
  • forks/.gitignore
    • Added a new .gitignore file to the forks/ directory to manage ignored files within the unified fork management structure.
  • forks/.pin/ccc/HEAD
    • Renamed ccc-fork/pins/HEAD to forks/.pin/ccc/HEAD.
  • forks/.pin/ccc/manifest
    • Renamed ccc-fork/pins/manifest to forks/.pin/ccc/manifest.
  • forks/.pin/ccc/res-2.resolution
    • Renamed ccc-fork/pins/res-2.resolution to forks/.pin/ccc/res-2.resolution.
    • Updated the conflict resolution format to include a SHA hash.
  • forks/.pin/ccc/res-4.resolution
    • Renamed ccc-fork/pins/res-4.resolution to forks/.pin/ccc/res-4.resolution.
    • Updated the conflict resolution format to include a SHA hash.
  • forks/.pin/forker/HEAD
    • Added forks/.pin/forker/HEAD to track the pinned HEAD for the self-managed forker tool.
  • forks/.pin/forker/manifest
    • Added forks/.pin/forker/manifest to store the manifest for the self-managed forker tool.
  • forks/config.json
    • Added a new config.json file in forks/ to unify configuration for all managed forks and reference repositories, including ccc, forker, contracts, and whitepaper.
  • package.json
    • Removed all fork: scripts and updated build, build:all, lint, clean, clean:deep, and check:full scripts to reflect the new forks/ directory structure.
    • Updated the version of @anthropic-ai/claude-code.
    • Removed the reference script.
  • packages/core/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • packages/dao/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • packages/dao/src/dao.ts
    • Corrected a typo in an error message from 'have different' to 'has different'.
  • packages/order/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • packages/sdk/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • packages/sdk/src/sdk.ts
    • Fixed a BigInt comparison bug by changing 0 to 0n.
  • packages/utils/package.json
    • Updated the build script to use tsgo-filter.sh from the root directory instead of fork-scripts/tsgo-filter.sh.
  • packages/utils/src/udt.ts
    • Removed @typescript-eslint/no-deprecated eslint-disable comments.
  • packages/utils/src/utils.ts
    • Corrected a typo in a doc comment from 'translation or that code' to 'translation of that code'.
  • pnpm-lock.yaml
    • Updated the pnpmfileChecksum.
    • Updated the version of @anthropic-ai/claude-code and @typescript/native-preview.
    • Updated all link: paths for @ckb-ccc/ packages from ccc-fork/ccc/ to forks/ccc/.
  • pnpm-workspace.yaml
    • Updated the generated workspace section markers from fork-workspaces to forker-workspaces.
    • Updated all package paths from ccc-fork/ccc/ to forks/ccc/.
  • reference/.gitignore
    • Removed the .gitignore file from the old reference/ directory.
  • reference/README.md
    • Removed the README.md file from the old reference/ directory.
  • reference/clone.sh
    • Removed the clone.sh script from reference/.
  • tsgo-filter.sh
    • Renamed fork-scripts/tsgo-filter.sh to tsgo-filter.sh.
    • Updated the script's logic to filter diagnostics based on the new forks/ directory structure and forks/config.json.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This is a substantial and well-executed structural refactor that unifies fork management under a new forks/ directory, consolidating what was previously scattered across ccc-fork/, fork-scripts/, and reference/. The new structure, with a centralized forks/config.json and a self-hosting forker tool, is a significant improvement in organization and clarity. The changes are applied consistently throughout the codebase, including all documentation and configuration files. The pull request also includes several beneficial small fixes, such as correcting a BigInt comparison bug, fixing typos, and optimizing the devcontainer setup. The overall quality of this refactoring is excellent. I have one minor suggestion for improving code style consistency.

@phroi
Copy link
Member Author

phroi commented Feb 25, 2026

LGTM

Phroi %272

@phroi phroi merged commit dd7b1d0 into master Feb 25, 2026
2 checks passed
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