@ggdna/dna-helix 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) ggdna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# dna_helix
+
+The DNA layer that tells a repo how to author a DNA layer of its own.
+
+It carries only that one topic and is one of the layers
+[dna_ggdna](https://github.com/ggdna/dna_ggdna) composes, so a repo gets
+it by taking the umbrella rather than by naming it.
+
+## Guides
+
+- `dna/doc/guides/dna-guide.md` — the `dna/` layout and the `dot-`
+  escape, what belongs in `_dna.json` and `_vars.json`, the three
+  override mechanisms, and publishing one layer to both registries
+
+## Skills
+
+- `/dna` — checks a layer against the DNA guide: paths that would not
+  instantiate, layers that are not dependencies, variables nothing
+  declares, and manifests that drifted apart
+
+## Layers
+
+Orthogonal, and parent-less like every topic layer of this organization.
+
+## Variables
+
+- `dnaCopyrightHolder` — the name in the license header of every file,
+  set to `ggdna` here
+
+## Usage
+
+Reach it through the umbrella:
+
+```bash
+pnpm add -D @ggdna/dna-ggdna   # TypeScript projects
+dart pub add dev:dna_ggdna     # Dart projects
+gg dna init
+```
+
+Naming this layer directly is for a repo that wants the authoring topic
+and nothing else:
+
+```bash
+pnpm add -D @ggdna/dna-helix
+dart pub add dev:dna_helix
+```
+
+The placed test instantiates and verifies the DNA on every test run.
+
+## Development
+
+The `dna/` folder is hand-authored source and is never generated. The repo
+instantiates its own DNA — run `dart test` after changes; commit first, a
+file the DNA would overwrite must not carry uncommitted work.

package/dna/_dna.json

@@ -0,0 +1,11 @@
+{
+  // This package is a DNA layer: dna/ is hand-authored source and is the
+  // last layer of its own instantiation.
+  "version": 1,
+
+  // No parent DNA. This layer is orthogonal: it carries only its own topic
+  // and is combined with dna_ggdna and other layers by the consumer. It
+  // stays parent-less on purpose — every other ggdna layer consumes it, so
+  // a parent here would close a cycle back through the umbrella.
+  "layers": []
+}

package/dna/_generated.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "layers": [
+    {
+      "name": "base",
+      "package": "helix",
+      "ecosystem": null,
+      "resolvedVersion": "1.3.0",
+      "via": null,
+      "hash": "0x705e486e88a93125"
+    },
+    {
+      "name": "self",
+      "package": null,
+      "ecosystem": null,
+      "resolvedVersion": null,
+      "via": null,
+      "hash": "0x3ef515a6d58f3d14"
+    }
+  ],
+  "claude": {
+    "claudeMdInclude": null
+  },
+  "baseVersion": "1.3.0",
+  "baseHash": "0x705e486e88a93125",
+  "instances": [
+    {
+      "path": ".claude/skills/dna/SKILL.md",
+      "hash": "0x0f192faea6dd65ab"
+    },
+    {
+      "path": "doc/guides/dna-guide.md",
+      "hash": "0x53f3df7f1bb005b3"
+    },
+    {
+      "path": "doc/hello_world.md",
+      "hash": "0x0903f7fc5224f6f1"
+    }
+  ]
+}

package/dna/_vars.json

@@ -0,0 +1,3 @@
+{
+  "dnaCopyrightHolder": "ggdna"
+}

package/dna/doc/guides/dna-guide.md

@@ -0,0 +1,122 @@
+<!--
+@license
+Copyright (c) dnaCopyrightHolder
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# DNA Guide
+
+How a DNA layer is built in this organization. A layer is an ordinary
+package whose `dna/` folder is hand-authored source; the engine merges it
+with the layers below and instantiates the result into the consuming
+repo.
+
+## Start a layer
+
+```bash
+mkdir dna_<topic> && cd dna_<topic>
+gg dna init
+```
+
+`gg dna init` places `dna/_dna.json` and the test that runs the engine.
+Everything else you write yourself.
+
+A new topic layer declares no parent, for two reasons. `dna_ggdna` lists
+every topic layer, so a layer that took the umbrella back would close a
+cycle and the engine refuses that. And a layer's parents reach every
+consumer of that layer — a parent here would push its content into every
+repo downstream, whether that repo asked for the topic or not. Keep the
+topic orthogonal; composing is what the umbrella is for.
+
+A repo that is not itself a topic layer takes the whole set in one go:
+
+```bash
+gg dna add dna_ggdna
+```
+
+## Lay out `dna/`
+
+`dna/` mirrors the root of the consuming repo — what sits at `dna/x/y`
+is instantiated to `x/y`:
+
+| In the layer | Instantiated to |
+| --- | --- |
+| `dna/LICENSE` | `LICENSE` |
+| `dna/doc/guides/x-guide.md` | `doc/guides/x-guide.md` |
+| `dna/dot-vscode/settings.json` | `.vscode/settings.json` |
+| `dna/dot-claude/skills/x/SKILL.md` | `.claude/skills/x/SKILL.md` |
+| `dna/_vars.json` | — private, stays inside |
+
+A leading dot is escaped as `dot-`, because publishing to pub drops every
+path that starts with a dot. Any path segment starting with `_` is
+private and never becomes an instance.
+
+## Declare what it inherits
+
+`dna/_dna.json` is the only place DNA configuration lives:
+
+```jsonc
+{
+  "version": 1,
+  // Application order — later layers win.
+  "layers": ["dna_readme", "dna_guides"]
+}
+```
+
+A layer with no parents declares `"layers": []`. Keep a topic layer
+orthogonal where you can: it is the umbrella layers that compose.
+
+## Name the variables
+
+Every variable starts with `dna` and is substituted as raw text, in any
+file type. Declare the defaults in `dna/_vars.json` and let the consumer
+override them:
+
+```json
+{ "dnaCopyrightHolder": "ggdna" }
+```
+
+Because substitution is textual, a variable also works inside a JSON
+string or a code fence — `dnaCompany` in a settings file is replaced the
+same way it is in prose.
+
+## Let consumers adapt it
+
+- A same-path file in a later layer replaces yours whole
+- `X.overrides.json` merges field-wise: objects deep-merge, `"key!"`
+  replaces without merging, `"key+"` appends to an array, `"key": null`
+  deletes
+- `X.overrides.md` replaces only the sections a markdown file marks with
+  `## @tag Title`
+
+Mark the sections of your guides that another organization will plausibly
+want to change — that is what makes a layer reusable instead of forkable.
+
+## Ship it to both registries
+
+A layer is consumed from Dart and from TypeScript, so it is published
+twice from the same repo:
+
+- `pubspec.yaml` — `name: dna_<topic>`, published to pub.dev
+- `package.json` — `name: @<scope>/dna-<topic>`, published to npm
+- `files: ["dna", "README.md", "LICENSE"]` — the tarball carries the
+  source folder, nothing built
+
+Keep both versions in step: the engine warns when the two copies of one
+layer differ, and uses the npm one.
+
+## Verify it
+
+The placed test instantiates the layer into its own repo on every run, so
+the layer is always exercised by the repo that ships it:
+
+```bash
+dart test      # or: pnpm test
+gg dna build   # the same run, without a test framework
+```
+
+Commit before a run that writes: every existing file the engine would
+overwrite has to be committed, so each overwrite stays recoverable
+through git.

package/dna/dot-claude/skills/dna/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: dna
+description: Checks this DNA layer against the DNA guide and reports what would break for a consumer. Use when the user says "/dna" or asks whether the layer is in shape.
+---
+
+<!--
+@license
+Copyright (c) dnaCopyrightHolder
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# DNA
+
+Read `doc/guides/dna-guide.md` and follow it.
+
+## 1. Check the layout
+
+Report a path below `dna/` that starts with a literal dot instead of
+`dot-`, a private `_` file that the layer expects to be instantiated, and
+a file that would land somewhere the consumer does not expect.
+
+## 2. Check the config
+
+Report a `dna/_dna.json` whose `layers` name something that is not a
+declared dependency, and a dependency that ships a `dna/` folder but is
+missing from `layers` — a dependency that is not listed is not a layer.
+
+## 3. Check the variables
+
+Report an identifier starting with `dna` that no `_vars.json` gives a
+value, and a value in `_vars.json` that nothing uses.
+
+## 4. Check both manifests
+
+Report a version mismatch between `pubspec.yaml` and `package.json`, and
+a layer listed in one manifest but not in the other — the engine warns
+when the two published copies differ.
+
+## 5. Report before fixing
+
+List the findings first. Fix only what the user confirms.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ggdna/dna-helix",
+  "version": "0.1.0",
+  "description": "DNA layer: how a DNA layer itself is built, configured and published",
+  "keywords": [
+    "dna",
+    "helix",
+    "conventions",
+    "scaffolding"
+  ],
+  "homepage": "https://github.com/ggdna/dna_helix",
+  "bugs": "https://github.com/ggdna/dna_helix/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ggdna/dna_helix.git"
+  },
+  "type": "module",
+  "files": [
+    "dna",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test:dart": "dart test",
+    "test": "pnpm run test:dart",
+    "prepublishOnly": "pnpm run test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "prettier": "^3.9.6"
+  }
+}