claat-build

claat Procedure Builder

manual.md is linted, and if it passes, HTML is generated. The design does not allow HTML to be created while lint is failing, so most of this skill's work isreading the diagnostics and fixing thembecomes.

Confirm the prerequisites

This tool operates in two stages.claat-tools inspects the input, and if it passes inspection, delegates HTML generation to claat on PATH. Therefore, two things are needed.

go version
claat version

claat is missing, install a verified version.

go install github.com/googlecodelabs/tools/claat@v0.0.0-20240220115335-873fe39d02dc

Run it

Run the CLI directly from the public tag.The working directory can be anywhere. Only on the first run, Go fetches the module. Only when you are developing claat itself and want to try your local changes, use ./cmd/claat-tools at the root of this repository instead.

go run github.com/nogikun/claat/cmd/claat-tools@v0.1.0 lint path/to/manual.md
go run github.com/nogikun/claat/cmd/claat-tools@v0.1.0 build -output output path/to/manual.md

build runs the same lint internally first. But at first, run lint on its own.build stops when lint fails, so it reduces back-and-forth to look at all the diagnostics first and fix them all at once.

Meaning of exit codes

code	Meaning	What to do next
0	Success	Check the generated output and report
1	Input lint error	Read the diagnostics and fix them (below)
2	Execution environment problem	claat not on PATH, invalid arguments, file cannot be read, not UTF-8
Other	claat itself failed	claat Read

Do not confuse 1 and 2. 1 is about fixing the document, and 2 is about fixing the environment.

Read the diagnostics and fix them

Diagnostics are output to standard error in the form path:line:column: error CODE message .

dev/manual.md:12:1: error STEP002 expected `Duration: H:M:SS` immediately after the step heading
dev/manual.md:48:5: error ASSET001 local image not found: images/setup.png

Principle of fixing: do not delete content just to silence lint. ASSET001 To remove ![...]() , dropping the line is the easiest and most harmful fix. The reader needed that image, which is why it was placed there. The error is an instruction to "prepare the image," not "stop referencing it."

code	Meaning	Decision
META001	Required metadata is missing	Fill in only what can be decided (status は Draft）。summary feedback link analytics account do not decide arbitrarily; ask
META002	Unknown key or duplicate key	Fix it. Only the 7 keys (summary id categories environments status feedback link analytics account) can be used. Before deleting one of the duplicates, confirm which value to keep
META003	Invalid value	Fix it.id は [A-Za-z0-9][A-Za-z0-9_-]* normalize to,environments は Web / Kiosk、status は Draft / Published / Deprecated / Hidden
DOC001	# title missing / multiple present / invalid position	Fix it. The second and later # is usually ## Since it is a typo, demote it. However, demoting it adds one step, so report what was fixed
STEP001	## is missing, or the heading level is invalid	Fix it.##### ###### は #### promote it to
STEP002	Duration is missing / position is invalid / format is invalid	Fix it.H:M:SS requires 3 delimiters, and 5:00 does not pass.## Place it on the first non-empty line immediately after. For steps without a value, estimate the required time from the content, propose it, and confirm
STEP003	The step body is empty	Return it to the writer. However, if the body consists only of a code block, this is the lint specification (inside the fence is not counted as body), and it can be fixed by adding one line of prose before the code
MD001	The code fence is not closed	Fix it. Determine where it should be closed from the surrounding context. The starting line appears in the diagnostic, so read from there
ASSET001	The relative image does not exist	Do not remove the reference. If it is a misspelling of the path, fix it. If the file itself does not exist, ask the user, including which screen to capture and where in images/ they want it placed

If a large amount of body text needs to be added, that becomes writing work rather than conversion.claat-writer Return it to the skill and run it including the Japanese check.

Check the generated output

build succeeds, claat が ok<TAB><id> is output, and the output is created with a name using the metadata id .

output/
└── <id>/
    ├── index.html
    └── codelab.json

The default output destination is output。-output(shortened -o) can be changed.Existing files are not deletedso,id If you change and regenerate it, the old directory remains. If it is unnecessary, deleting it is the responsibility of the side that executed it.

After generation, confirm that index.html was actually created before reporting. Even if lint passes, if it fails on the claat side, the exit code is claat becomes that of

If you want to check the appearance locally, claat serve can be used.

Report

Tell the user the following.

• Generated index.html path of
• Locations fixed by lint (what was fixed and why)
• Locations left unfixed and what you want the user to do (image placement,summary wording, etc.)

Unless requested, do not commit or publish the generated output.