clod-0.1.0: SPEC.md

# Clod specification

*** LLMs may only modify this file with explicit permission from the user. ***
*** In the case where our implementation or documentation diverge from this
document consider this document authoritative--however ask the user for
confirmation before bringing them in sync as the human may have forgotten
to update this document and we don't want to take off in the wrong
direction. ***
*** Please note not all program behavior is documented here (yet) ***

## Filename transformation for Claude UI

We transform project file names for upload to Claude's UI by flattening the
path--this allows users to differentiate between, say a package.json file in
the project root and a package.json file under app/lib/plugin -- the name of
the former file won't be modified as it is in the project root. The name of the
latter file (app/lib/plugin/package.json) will be transformed to
app-lib-plugin-package.json -- a manifest file is created containing a mapping
between the original and transformed names that Claude Filesystem Access--or
the user--can use to write modified files back to their original locations.

This manifest must be generated with a mapping of all eligible files, even when
only some files--or none at all--have changed. This is because there will only
be a single copy of the manifest--the most recent--in Claude's Project
Knowledge section.

Hidden files and directories--those beginning with a '.'--must have the dot
removed during transformation. The intent is that the user will copy and paste
these files from their Finder window to the Claude UI, but files that start
with a dot will be hidden from the Finder and thus won't be copied. (yes, it is
possible to view hidden files in Finder, but that's a pain in the butt). To
prevent potential conflicts we should prepend these with 'dot--', as in
.tool-versions would be transformed to dot--tool-versions. The two - convention
is used to prevent confusion in the case of a directory literally named 'dot'.
Of course it is possible for a file or directory to start with '-' but it is
pretty rare in the wild.

In the specific case of SVG files we work around a restriction in Claude's UI
where files with SVG file extensions are rejected from the uploader. We exclude
them in our default .clodignore file, but since Claude actually can use them just
fine as XML files the user can choose to include them (by removing their entry
from .clodignore) and we'll transform them into files with XML extensions--for
example assets/images/logo.svg becomes assets-images-logo-svg.xml

## Clean up previous staging directory

Clod stores the most recent staging directory in db.dhall, when we run clod
again it deletes the previous staging directory.

## Output

This is a Unix tool and is expected to act like one. The only output from
stdout should be the path of the staging directory and we should be able to eg use
open `clod` to view it on macOS. Any other output should go to stderr but,
except in the case of actual errors, it should only output when the verbose
flag is passed.

## First run vs subsequent runs

The first run (no database exists) copies all files to the staging
directory. Subsequent runs copy only modified files.

## Examples

A user goes to a new project directory and runs clod. All of their files should
be copied to the staging directory along with the manifest file. Without
changing anything a user runs clod again--the only thing that should be copied
to the staging directory is the manifest file, which should contain a complete
mapping of all eligible files.