lib/App/Dapper/Agents.pm

filter: Statementstmt 19.2% 26 / 135 Branchbran 0.0% 0 / 58 Conditioncond 0.0% 0 / 21 MC/DCmcdc 0.0% 0 / 12 Subroutinesub 61.5% 8 / 13 Podpod 100% 2 / 2 totaltotal 14.9% 36 / 241 CC 42 SCAR 59.8
CC
42
Cov
12%
guide
756.0
_layout_description
72.0
update
42.0
CRAP 394.4
« lib/App/Dapper/Import.pm ↑ Summary lib/App/Dapper/Deploy.pm »
1 package App::Dapper::Agents;
2  
3 =head1 NAME
4  
5 App::Dapper::Agents - Explain a Dapper project to AI coding agents.
6  
7 =head1 DESCRIPTION
8  
9 C<dapper init> writes an C<AGENTS.md> file that tells AI coding agents (and
10 people) how the project works: where pages, layouts and data live, which
11 front matter each kind of page needs, the rules Dapper enforces, and the
12 commands to run. A C<CLAUDE.md> points Claude Code at it.
13  
14 C<dapper agents> brings C<AGENTS.md> up to date after the project changes.
15 The part Dapper writes sits between C<< <!-- dapper:begin --> >> and
16 C<< <!-- dapper:end --> >>; anything outside those lines (your own notes, or
17 a theme's) is kept.
18  
19 =cut
20  
21 190 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
22 190 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 190 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
24 190 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 190 ▶use File::Basename qw/ dirname /;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 190 ▶use File::Find ();
Subroutine BEGIN: called CC=1 SCAR=0.0
28  
29 190 ▶use App::Dapper::Utils;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 190 ▶use App::Dapper::Schema;
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 190 my $BEGIN = '<!-- dapper:begin (this part is written by "dapper agents"; edit outside it) -->';
33 190 my $END = '<!-- dapper:end -->';
34  
35 =head2 update
36  
37 Takes a Dapper object (and optionally extra notes for a new file), and writes
38 or updates C<AGENTS.md> in the current directory, and a C<CLAUDE.md> if there
39 isn't one. Returns the list of files written.
40  
41 =cut
42  
43 0 ▶sub update {
Subroutine update: not called CC=6 SCAR=37.4
Pod documented
44 0 my ($dapper, $notes) = @_;
45  
46 0 my $generated = "$BEGIN\n" . guide($dapper) . "$END\n";
47 0 my @written;
48  
49 0 my $file = 'AGENTS.md';
50 0 ▶ if (-f $file) {
Branch: 1 branch
BranchTrueFalseTotal
if (-f $file) { } 0 0 0
51 0 my $text = App::Dapper::Utils::read_file($file);
52 0 ▶ if ($text =~ s/\Q$BEGIN\E.*?\Q$END\E\n?/$generated/s) {
Branch: 1 branch
BranchTrueFalseTotal
if ($text =~ s/\Q$BEGIN\E.*?\Q$END\E\n?/$generated/s) { } 0 0 0
53 0 App::Dapper::Utils::write_file($file, $text);
54 }
55 else {
56 0 App::Dapper::Utils::write_file($file, "$text\n$generated");
57 }
58 }
59 else {
60 0 my $text = $generated;
61 0 ▶ $text .= "\n$notes" if defined $notes and length $notes;
Branch: 1 branch
BranchTrueFalseTotal
if defined $notes and length $notes 0 0 0
Condition0%0/3
defined $notes and length $notes
!ll&&!rl&&r
000
MC/DC0%0/2
defined $notes and length $notes
defined $notes length $notes
Truth table0%0/3
A and B
A= defined $notesB= length $notes
ABresult
0X0
100
111
62 0 App::Dapper::Utils::write_file($file, $text);
63 }
64 0 push @written, $file;
65  
66 0 ▶ if (not -e 'CLAUDE.md') {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e "CLAUDE.md") 0 0 0
67 0 App::Dapper::Utils::write_file('CLAUDE.md',
68 "This site is built with Dapper. Read AGENTS.md before making changes.\n\n\@AGENTS.md\n");
69 0 push @written, 'CLAUDE.md';
70 }
71  
72 0 return @written;
73 }
74  
75 =head2 guide
76  
77 Takes a Dapper object and returns the guide to the project, in Markdown.
78  
79 =cut
80  
81 0 ▶sub guide {
Subroutine guide: not called CC=27 SCAR=66.3
Pod documented
82 0 my ($dapper) = @_;
83  
84 0 my $loaded = eval {
85 0 local $dapper->{quiet} = 1;
86 0 local $dapper->{collect} = 1;
87 0 $dapper->{problems} = [];
88 0 $dapper->{written} = {};
89 0 $dapper->{page_owner} = {};
90 0 $dapper->parse();
91 0 $dapper->transform();
92 0 1;
93 };
94  
95 0 my $site = $dapper->{site};
96 0 my ($source, $layout, $output, $data) = map { $dapper->{$_} } qw/ source layout output data_dir /;
97 # Without a project file the directories are not resolved; use the defaults
98 0 ▶ $data = defined $site->{data_dir} ? $site->{data_dir} : '_data' unless defined $data;
Branch: 2 branches
BranchTrueFalseTotal
unless defined $data 0 0 0
defined $site->{'data_dir'} ? : 0 0 0
99 0 ▶ my $name = defined $site->{name} ? $site->{name} : 'this site';
Branch: 1 branch
BranchTrueFalseTotal
defined $site->{'name'} ? : 0 0 0
100  
101 0 my $text = <<"MD";
102 # Working on $name
103  
104 This is a static website built with [Dapper](https://github.com/markdbenson/dapper).
105 Pages are Markdown or HTML files with YAML front matter; layouts turn them into
106 HTML in `$output/`. Edit the source files, never the output.
107  
108 ## Commands
109  
110 - `dapper serve`: build, watch for changes and serve the site at http://localhost:8000
111 - `dapper check --json`: find problems (broken links, front matter that doesn't match
112 a schema, missing layouts, template errors). **Run it after every change and fix
113 every error it reports.**
114 - `dapper build`: build the site into `$output/`
115 MD
116 0 ▶ $text .= "- `dapper deploy`: build, check and publish the site\n" if $site->{deploy};
Branch: 1 branch
BranchTrueFalseTotal
if $site->{"deploy"} 0 0 0
117 0 $text .= "- `dapper agents`: update this file after adding layouts, schemas or settings\n";
118  
119 0 $text .= <<"MD";
120  
121 ## Where things are
122  
123 - `$source/`: the pages. A file's path decides its URL unless it has `categories` or
124 a `urlpattern` (then its URL comes from the pattern; posts usually live here).
125 - `$layout/`: the layouts, which are templates (Template Toolkit syntax, `[% ... %]`).
126 - `$data/`: data files (YAML or JSON), available in templates as `site.data`.
127 - `$dapper->{config}`: the site's settings.
128 - Other top-level files and folders (CSS, images, scripts) are copied to the output
129 as they are, except names starting with `.` or `_`.
130 MD
131  
132 0 ▶ my @layouts = sort keys %{ $dapper->{layout_content} || {} };
Condition0%0/2
$dapper->{'layout_content'} || {}
l!l
00
MC/DC0%0/1
$dapper->{'layout_content'} || {}
$dapper->{'layout_content'}
Truth table0%0/2
A
A= $dapper->{'layout_content'}
Aresult
11
00
133 0 ▶ if (@layouts) {
Branch: 1 branch
BranchTrueFalseTotal
if (@layouts) 0 0 0
134 0 $text .= "\n## Layouts\n\n";
135 0 for my $name (@layouts) {
136 0 my $description = _layout_description($dapper, $name);
137 0 ▶ $text .= "- `$name`" . (defined $description ? ": $description" : '') . "\n";
Branch: 1 branch
BranchTrueFalseTotal
defined $description ? : 0 0 0
138 }
139 0 $text .= "\nA page uses the layout named by its `layout` setting, or `index` if it has none.\n";
140 }
141  
142 0 my @schemas = _schemas($dapper);
143 0 ▶ if (@schemas) {
Branch: 1 branch
BranchTrueFalseTotal
if (@schemas) 0 0 0
144 0 $text .= "\n## Front matter rules\n\n";
145 0 $text .= "Pages must match the `_schema.yml` that applies to their folder; the build refuses\n";
146 0 $text .= "pages that don't.\n\n";
147 0 for my $schema (@schemas) {
148 0 my $dir = dirname($schema->{file});
149 0 $text .= "### `$dir/`\n\n";
150 0 ▶ $text .= "- Required: " . join(', ', map { "`$_`" } @{$schema->{required}}) . "\n" if @{$schema->{required}};
Branch: 1 branch
BranchTrueFalseTotal
if @{$schema->{"required"};} 0 0 0
151 0 for my $field (sort keys %{$schema->{fields}}) {
152 0 my $rules = $schema->{fields}->{$field};
153 0 my @parts = ($rules->{type});
154 0 ▶ push @parts, 'one of ' . join(', ', map { "`$_`" } @{$rules->{values}}) if $rules->{values};
Branch: 1 branch
BranchTrueFalseTotal
if $rules->{"values"} 0 0 0
155 0 ▶ push @parts, "at most $rules->{max_length} characters" if defined $rules->{max_length};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"max_length"} 0 0 0
156 0 ▶ push @parts, "at least $rules->{min_length} characters" if defined $rules->{min_length};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"min_length"} 0 0 0
157 0 ▶ push @parts, "from $rules->{min}" if defined $rules->{min};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"min"} 0 0 0
158 0 ▶ push @parts, "up to $rules->{max}" if defined $rules->{max};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"max"} 0 0 0
159 0 ▶ push @parts, "matching `$rules->{pattern}`" if defined $rules->{pattern};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"pattern"} 0 0 0
160 0 $text .= "- `$field`: " . join(', ', @parts) . "\n";
161 }
162 0 ▶ $text .= "- Other fields are not allowed\n" unless $schema->{additional};
Branch: 1 branch
BranchTrueFalseTotal
unless $schema->{"additional"} 0 0 0
163 0 $text .= "\n";
164 }
165 }
166 0 $text =~ s/\n\n\z/\n/;
167  
168 0 ▶ if ($loaded) {
Branch: 1 branch
BranchTrueFalseTotal
if ($loaded) 0 0 0
169 0 ▶ my @categories = sort keys %{ $site->{categories} || {} };
Condition0%0/2
$site->{'categories'} || {}
l!l
00
MC/DC0%0/1
$site->{'categories'} || {}
$site->{'categories'}
Truth table0%0/2
A
A= $site->{'categories'}
Aresult
11
00
170 0 ▶ my @tags = sort keys %{ $site->{tags} || {} };
Condition0%0/2
$site->{'tags'} || {}
l!l
00
MC/DC0%0/1
$site->{'tags'} || {}
$site->{'tags'}
Truth table0%0/2
A
A= $site->{'tags'}
Aresult
11
00
171 0 ▶ if (@categories or @tags) {
Branch: 1 branch
BranchTrueFalseTotal
if (@categories or @tags) 0 0 0
Condition0%0/3
@categories or @tags
l!l&&r!l&&!r
000
MC/DC0%0/2
@categories or @tags
@categories @tags
Truth table0%0/3
A or B
A= @categoriesB= @tags
ABresult
1X1
011
000
172 0 $text .= "\n## Categories and tags in use\n\n";
173 0 ▶ $text .= "- Categories: " . join(', ', map { "`$_`" } @categories) . "\n" if @categories;
Branch: 1 branch
BranchTrueFalseTotal
if @categories 0 0 0
174 0 ▶ $text .= "- Tags: " . join(', ', map { "`$_`" } @tags) . "\n" if @tags;
Branch: 1 branch
BranchTrueFalseTotal
if @tags 0 0 0
175 0 $text .= "\nReuse these where they fit rather than inventing near-duplicates.\n";
176 }
177 }
178  
179 0 $text .= <<'MD';
180  
181 ## Rules
182  
183 - **Content is not a template.** `[% ... %]` in a page is shown as text. Only add
184 `template: true` to a page that needs template code (such as a list of posts);
185 layouts are always templates.
186 - **Dates** are written like `2026-01-01T09:00:00` (or `2026-01-01`).
187 - **Every page needs a `title`**; give pages a `description` (about 150 characters)
188 for search engines, social media and AI tools.
189 - **Links between pages** start with `/` (for example `/about.html` or
190 `/blog/2026/01/my-post/`). `dapper check` reports links that lead nowhere.
191 - **Images** need meaningful alt text: `![A loaf of sourdough on a board](/images/loaf.jpg)`.
192 - **Components** add what Markdown can't, without template code: `::: note`, `::: tip`
193 and `::: warning` boxes (closed with `:::` on its own line), `::: details "Summary"`,
194 `::: gallery`, and single lines such as `::: youtube <address> "Title"`,
195 `::: button /contact/ "Get in touch"` and `::: figure photo.jpg "Alt text" "Caption"`.
196 - **Drafts:** `draft: true` keeps a page off the site, and so does a `date` in the
197 future, until that date. `dapper serve` shows them; `dapper check` lists them.
198 - When you rename or move a page, add a redirect from its old URL in
199 `_data/redirects.yml` (`/old-url/: /new-url/`).
200 - In layouts, don't name template variables after directives (`next`, `last`, `loop`,
201 `block`, `wrapper`, ...): Dapper's templates are case-insensitive, so they are read as
202 directives. Use names like `later` or `count` instead.
203 - Don't edit or commit the output directory or `.dapper/`.
204 MD
205 0 $text =~ s{`_data\/redirects\.yml`}{`$data\/redirects.yml`}g;
206  
207 0 return $text;
208 }
209  
210 0 ▶sub _layout_description {
Subroutine _layout_description: not called CC=8 SCAR=42.8
211 0 my ($dapper, $name) = @_;
212  
213 0 my $file;
214 0 for my $candidate (App::Dapper::Utils::read_dir($dapper->{layout})) {
215 0 ▶ if (App::Dapper::Utils::filter_stem($candidate) eq $name) { $file = "$dapper->{layout}/$candidate"; last }
Branch: 1 branch
BranchTrueFalseTotal
if (App::Dapper::Utils::filter_stem($candidate) eq $name) 0 0 0
216 }
217 0 ▶ return unless defined $file and -f $file;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $file and -f $file 0 0 0
Condition0%0/3
defined $file and -f $file
!ll&&!rl&&r
000
MC/DC0%0/2
defined $file and -f $file
defined $file -f $file
Truth table0%0/3
A and B
A= defined $fileB= -f $file
ABresult
0X0
100
111
218  
219 0 my ($frontmatter) = eval { App::Dapper::Utils::split_frontmatter(App::Dapper::Utils::read_file($file), $file) };
220 0 ▶ return unless ref $frontmatter eq 'HASH' and defined $frontmatter->{description} and !ref $frontmatter->{description};
Branch: 1 branch
BranchTrueFalseTotal
unless ref $frontmatter eq "HASH" and defined $frontmatter->{"description"} and not ref $frontmatter->{"description"} 0 0 0
Condition0%0/6
ref $frontmatter eq "HASH" and defined $frontmatter->{"description"} and not ref $frontmatter->{"description"}
!ll&&!rl&&r
000
ref $frontmatter eq "HASH" and defined $frontmatter->{"description"}
!ll&&!rl&&r
000
MC/DC0%0/3
ref $frontmatter eq "HASH" and defined $frontmatter->{"description"} and not ref $frontmatter->{"description"}
ref $frontmatter eq "HASH" defined $frontmatter->{"description"} not ref $frontmatter->{"description"}
Truth table0%0/4
A and B and not(C)
A= ref $frontmatter eq "HASH"B= defined $frontmatter->{"description"}C= not ref $frontmatter->{"description"}
ABCresult
0XX0
10X0
1100
1111
221 0 return $frontmatter->{description};
222 }
223  
224 0 ▶sub _schemas {
Subroutine _schemas: not called CC=2 SCAR=17.9
225 0 my ($dapper) = @_;
226  
227 0 my @schemas;
228 0 ▶ return unless -d $dapper->{source};
Branch: 1 branch
BranchTrueFalseTotal
unless -d $dapper->{"source"} 0 0 0
229 File::Find::find({
230 no_chdir => 1,
231 0 ▶ wanted => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
232 0 my $name = App::Dapper::Utils::name_chars($File::Find::name);
233 0 ▶ return unless $name =~ m{(?:^|/)_schema\.yml$};
Branch: 1 branch
BranchTrueFalseTotal
unless $name =~ m[(?:^|/)_schema\.yml$] 0 0 0
234 0 my $schema = eval { App::Dapper::Schema::load($name) };
235 0 ▶ push @schemas, $schema if $schema;
Branch: 1 branch
BranchTrueFalseTotal
if $schema 0 0 0
236 },
237 0 }, App::Dapper::Utils::name_bytes($dapper->{source}));
238  
239 0 return sort { $a->{file} cmp $b->{file} } @schemas;
240 }
241  
242 190 1;
« lib/App/Dapper/Import.pm ↑ Summary lib/App/Dapper/Deploy.pm »