lib/App/Dapper/Agents.pm

filter: Statementstmt 19.5% 26 / 133 Branchbran 0.0% 0 / 54 Conditioncond 0.0% 0 / 21 MC/DCmcdc 0.0% 0 / 12 Subroutinesub 61.5% 8 / 13 Podpod 100% 2 / 2 totaltotal 15.3% 36 / 235 CC 40 SCAR 58.0
CC
40
Cov
12%
guide
650.0
_layout_description
72.0
update
42.0
CRAP 329.5
« lib/App/Dapper/Publish.pm ↑ Summary lib/App/Dapper.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 32 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
22 32 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 32 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
24 32 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 32 ▶use File::Basename qw/ dirname /;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 32 ▶use File::Find ();
Subroutine BEGIN: called CC=1 SCAR=0.0
28  
29 32 ▶use App::Dapper::Utils;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 32 ▶use App::Dapper::Schema;
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 32 my $BEGIN = '<!-- dapper:begin (this part is written by "dapper agents"; edit outside it) -->';
33 32 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=25 SCAR=64.8
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 0 ▶ my $name = defined $site->{name} ? $site->{name} : 'this site';
Branch: 1 branch
BranchTrueFalseTotal
defined $site->{'name'} ? : 0 0 0
98  
99 0 my $text = <<"MD";
100 # Working on $name
101  
102 This is a static website built with [Dapper](https://github.com/markdbenson/dapper).
103 Pages are Markdown or HTML files with YAML front matter; layouts turn them into
104 HTML in `$output/`. Edit the source files, never the output.
105  
106 ## Commands
107  
108 - `dapper serve`: build, watch for changes and serve the site at http://localhost:8000
109 - `dapper check --json`: find problems (broken links, front matter that doesn't match
110 a schema, missing layouts, template errors). **Run it after every change and fix
111 every error it reports.**
112 - `dapper build`: build the site into `$output/`
113 MD
114 0 ▶ $text .= "- `dapper deploy`: build, check and publish the site\n" if $site->{deploy};
Branch: 1 branch
BranchTrueFalseTotal
if $site->{"deploy"} 0 0 0
115 0 $text .= "- `dapper agents`: update this file after adding layouts, schemas or settings\n";
116  
117 0 $text .= <<"MD";
118  
119 ## Where things are
120  
121 - `$source/`: the pages. A file's path decides its URL unless it has `categories` or
122 a `urlpattern` (then its URL comes from the pattern; posts usually live here).
123 - `$layout/`: the layouts, which are templates (Template Toolkit syntax, `[% ... %]`).
124 - `$data/`: data files (YAML or JSON), available in templates as `site.data`.
125 - `$dapper->{config}`: the site's settings.
126 - Other top-level files and folders (CSS, images, scripts) are copied to the output
127 as they are, except names starting with `.` or `_`.
128 MD
129  
130 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
131 0 ▶ if (@layouts) {
Branch: 1 branch
BranchTrueFalseTotal
if (@layouts) 0 0 0
132 0 $text .= "\n## Layouts\n\n";
133 0 for my $name (@layouts) {
134 0 my $description = _layout_description($dapper, $name);
135 0 ▶ $text .= "- `$name`" . (defined $description ? ": $description" : '') . "\n";
Branch: 1 branch
BranchTrueFalseTotal
defined $description ? : 0 0 0
136 }
137 0 $text .= "\nA page uses the layout named by its `layout` setting, or `index` if it has none.\n";
138 }
139  
140 0 my @schemas = _schemas($dapper);
141 0 ▶ if (@schemas) {
Branch: 1 branch
BranchTrueFalseTotal
if (@schemas) 0 0 0
142 0 $text .= "\n## Front matter rules\n\n";
143 0 $text .= "Pages must match the `_schema.yml` that applies to their folder; the build refuses\n";
144 0 $text .= "pages that don't.\n\n";
145 0 for my $schema (@schemas) {
146 0 my $dir = dirname($schema->{file});
147 0 $text .= "### `$dir/`\n\n";
148 0 ▶ $text .= "- Required: " . join(', ', map { "`$_`" } @{$schema->{required}}) . "\n" if @{$schema->{required}};
Branch: 1 branch
BranchTrueFalseTotal
if @{$schema->{"required"};} 0 0 0
149 0 for my $field (sort keys %{$schema->{fields}}) {
150 0 my $rules = $schema->{fields}->{$field};
151 0 my @parts = ($rules->{type});
152 0 ▶ push @parts, 'one of ' . join(', ', map { "`$_`" } @{$rules->{values}}) if $rules->{values};
Branch: 1 branch
BranchTrueFalseTotal
if $rules->{"values"} 0 0 0
153 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
154 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
155 0 ▶ push @parts, "from $rules->{min}" if defined $rules->{min};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"min"} 0 0 0
156 0 ▶ push @parts, "up to $rules->{max}" if defined $rules->{max};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"max"} 0 0 0
157 0 ▶ push @parts, "matching `$rules->{pattern}`" if defined $rules->{pattern};
Branch: 1 branch
BranchTrueFalseTotal
if defined $rules->{"pattern"} 0 0 0
158 0 $text .= "- `$field`: " . join(', ', @parts) . "\n";
159 }
160 0 ▶ $text .= "- Other fields are not allowed\n" unless $schema->{additional};
Branch: 1 branch
BranchTrueFalseTotal
unless $schema->{"additional"} 0 0 0
161 0 $text .= "\n";
162 }
163 }
164 0 $text =~ s/\n\n\z/\n/;
165  
166 0 ▶ if ($loaded) {
Branch: 1 branch
BranchTrueFalseTotal
if ($loaded) 0 0 0
167 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
168 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
169 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
170 0 $text .= "\n## Categories and tags in use\n\n";
171 0 ▶ $text .= "- Categories: " . join(', ', map { "`$_`" } @categories) . "\n" if @categories;
Branch: 1 branch
BranchTrueFalseTotal
if @categories 0 0 0
172 0 ▶ $text .= "- Tags: " . join(', ', map { "`$_`" } @tags) . "\n" if @tags;
Branch: 1 branch
BranchTrueFalseTotal
if @tags 0 0 0
173 0 $text .= "\nReuse these where they fit rather than inventing near-duplicates.\n";
174 }
175 }
176  
177 0 $text .= <<'MD';
178  
179 ## Rules
180  
181 - **Content is not a template.** `[% ... %]` in a page is shown as text. Only add
182 `template: true` to a page that needs template code (such as a list of posts);
183 layouts are always templates.
184 - **Dates** are written like `2026-01-01T09:00:00` (or `2026-01-01`).
185 - **Every page needs a `title`**; give pages a `description` (about 150 characters)
186 for search engines, social media and AI tools.
187 - **Links between pages** start with `/` (for example `/about.html` or
188 `/blog/2026/01/my-post/`). `dapper check` reports links that lead nowhere.
189 - **Images** need meaningful alt text: `![A loaf of sourdough on a board](/images/loaf.jpg)`.
190 - When you rename or move a page, add a redirect from its old URL in
191 `_data/redirects.yml` (`/old-url/: /new-url/`).
192 - In layouts, don't name template variables after directives (`next`, `last`, `loop`,
193 `block`, `wrapper`, ...): Dapper's templates are case-insensitive, so they are read as
194 directives. Use names like `later` or `count` instead.
195 - Don't edit or commit the output directory or `.dapper/`.
196 MD
197  
198 0 return $text;
199 }
200  
201 0 ▶sub _layout_description {
Subroutine _layout_description: not called CC=8 SCAR=42.8
202 0 my ($dapper, $name) = @_;
203  
204 0 my $file;
205 0 for my $candidate (App::Dapper::Utils::read_dir($dapper->{layout})) {
206 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
207 }
208 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
209  
210 0 my ($frontmatter) = eval { App::Dapper::Utils::split_frontmatter(App::Dapper::Utils::read_file($file), $file) };
211 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
212 0 return $frontmatter->{description};
213 }
214  
215 0 ▶sub _schemas {
Subroutine _schemas: not called CC=2 SCAR=17.9
216 0 my ($dapper) = @_;
217  
218 0 my @schemas;
219 0 ▶ return unless -d $dapper->{source};
Branch: 1 branch
BranchTrueFalseTotal
unless -d $dapper->{"source"} 0 0 0
220 File::Find::find({
221 no_chdir => 1,
222 0 ▶ wanted => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
223 0 my $name = App::Dapper::Utils::name_chars($File::Find::name);
224 0 ▶ return unless $name =~ m{(?:^|/)_schema\.yml$};
Branch: 1 branch
BranchTrueFalseTotal
unless $name =~ m[(?:^|/)_schema\.yml$] 0 0 0
225 0 my $schema = eval { App::Dapper::Schema::load($name) };
226 0 ▶ push @schemas, $schema if $schema;
Branch: 1 branch
BranchTrueFalseTotal
if $schema 0 0 0
227 },
228 0 }, App::Dapper::Utils::name_bytes($dapper->{source}));
229  
230 0 return sort { $a->{file} cmp $b->{file} } @schemas;
231 }
232  
233 32 1;
« lib/App/Dapper/Publish.pm ↑ Summary lib/App/Dapper.pm »