Add safety check before package pruning

Verifies all state packages are installed locally before running markAllAsDeps and orphan cleanup.
Improve tarball selection when installing AUR packages
2026-05-04 23:28:58 +02:00 · 2026-05-04 22:47:07 +02:00 · 2026-05-04 21:13:25 +02:00 · 2026-05-04 20:25:43 +02:00 · 2026-05-03 23:04:34 +02:00 · 2026-05-03 22:17:51 +02:00
65 changed files with 3549 additions and 144 deletions
@@ -30,3 +30,6 @@ go.work.sum
 # Editor/IDE
 # .idea/
 # .vscode/
+
+# Binary output
+bin/
@@ -2,4 +2,4 @@
 description: Make a git commit, asking if it was by the user or AI
 ---

-skill name=make-commit $1
+skill [name=make-commit] message: $1
@@ -0,0 +1,28 @@
+---
+description: Fixup diverging archived openspec change artifacts
+---
+
+Fixup archived openspec change artifacts in @openspec/changes/archive/ that have diverged from the codebase.
+
+For each archived change directory:
+1. Read the .md artifact
+2. Review related code to verify consistency
+3. Fix any mismatches (status, fields, missing links, etc.)
+
+Only run make-commit if changes were made, with a specific message like "Fixup: add missing X field to Y change".
+
+---
+
+**Steps**
+
+1. **For each archived openspec change**
+
+   Read the change artifact.
+
+   Go through the related code.
+
+   Correct the change artifact where needed.
+
+2. **Run make-commit if changes were made**
+
+   skill [name=make-commit] message: "Fixup: <specific fix>"
@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
@@ -7,16 +7,29 @@ description: >
 license: GPL-3.0
 metadata:
  author: riyyi
-  version: "1.0"
+  version: "1.1"
 ---

 Make a git commit, distinguishing between user and AI contributions.

 ---

+**Commit message format**
+
+A valid commit message consists of a required **title** and an optional **body**:
+
+Rules:
+- **Title** (required): max 72 characters, starts with a capital letter —
+  unless referring to a tool/project that explicitly uses lowercase (e.g.,
+  "go", "npm", "rustc"). No trailing period.
+- **Body** (optional): any further elaboration. Each line max 72 characters.
+  Wrap manually — do not rely on the terminal to wrap.
+
+---
+
 **Steps**

-1. **Ask user if this commit is by them or by AI**
+1. **[REQUIRED] Ask user if this commit is by them or by AI**

   Use the **question tool** to ask:
   > "Was this commit made by you or by AI?"
@@ -25,55 +38,63 @@ Make a git commit, distinguishing between user and AI contributions.
   - "By me" - User made the commit
   - "By AI" - AI made the commit

-2. **Check for commit message**
+2. **Compose the commit message**

-   If the user did NOT provide a commit message, generate one from staged changes:
+   If the user did NOT provide a commit message, generate one from staged
+   changes:
   ```bash
-   git diff --staged --stat
+   git --no-pager diff --staged
   ```
-   Create a reasonable commit message based on the changes.
+   Write a commit message following the format above.

-   **Capitalization rule**: Commit message should start with a capital letter,
-   unless it refers to a tool or project that explicitly uses lowercase as its
-   name (e.g., "go", "npm", "rustc").
+   If the user **DID** provide a message, treat it as raw input and apply the
+   format rules to it.

-3. **Show commit message and confirm**
+3. **Validate the commit message**

-   Display the commit message to the user.
+   Before presenting the message to the user, check it against every rule:
+
+   - [ ] Title is present and non-empty
+   - [ ] Title is at most 72 characters
+   - [ ] Title starts with a capital letter (or an intentionally lowercase name)
+   - [ ] Title has no trailing period
+   - [ ] Every line in the body is at most 72 characters
+
+   Fix any violations silently before showing the message to the user.
+
+4. **Show commit message and confirm**

   Use the **question tool** to ask:
   > "Is this commit message okay, or would you like to make tweaks?"
+   > ```
+   > <message>
+   > ```

   Options:
   - "Looks good" - Proceed with this message
-   - "Make tweaks" - User will provide a new message
+   - "Make tweaks" - User will provide a new message or describe changes

-   **If user wants tweaks**: Ask them for the new commit message.
-
-4. **Get git user config**
-
-   ```bash
-   git config user.name
-   git config user.email
-   ```
+   **If user wants tweaks**: apply the same validation (step 3) to the revised
+   message before committing.

 5. **Make the commit**

-   Use the commit message provided by the user.
-
-   **If by user:**
+   For a title-only message:
   ```bash
-   git commit -m "<message>"
+   git commit -m "<title>"
   ```
-   (Uses git config user as both committer and author)

-   **If by AI:**
+   For a message with a body, pass `-m` twice (git inserts the blank line):
   ```bash
-   git -c user.name="<git-config-name>" -c user.email="<git-config-email>" commit -m "<message>" --author="AI Bot <ai@local>"
+   git commit -m "<title>" -m "<body>"
+   ```
+
+   Append `--author="AI Bot <ai@local>"` when the commit is by AI:
+   ```bash
+   git commit -m "<title>" [-m "<body>"] --author="AI Bot <ai@local>"
   ```
-   (Uses git config for committer, but sets author to AI Bot)

 **Output**

- Tell user the commit was made
- If AI commit, mention that the author was set to "AI Bot <ai@local>"
+- Tell user the commit was made.
+- If AI commit, mention that the author was set to "AI Bot <ai@local>".
@@ -2,6 +2,30 @@

 ## Skills: Always Active

-At the start of every conversation, load the following skills using the `skill` tool before responding to the user:
+At the start of every conversation, load the following skills using the `skill`
+tool before responding to the user:

 1. **caveman** — Always use caveman mode (full intensity) for all responses
+
+## Code Organization
+
+### Go: File Structure
+- Variables must appear at the top of each file.
+- Types must appear after variables.
+- Constructors must appear after types.
+- Public (exported) functions must appear after constructors.
+- Private (unexported) functions must appear at the bottom of each file.
+- Within each section, definitions must be sorted alphabetically by name.
+- The sections must be separated by exactly these dividers, filling in the section:
+
+	// -----------------------------------------
+	// <section>
+
+### Go: Line Length
+
+Keep Go lines as short as reasonably possible.
+
+- **Hard limit:** 120 characters — never exceed this.
+- **Preferred:** 100 characters or fewer in normal cases.
+- **Target:** 80 characters if breaking the line produces cleaner, more readable
+  code (e.g. chained calls, long argument lists, multi-condition `if` statements).
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
@@ -0,0 +1,46 @@
+.PHONY: build fmt fmtcheck vet check githook install uninstall
+
+PKG := github.com/Riyyi/declpac
+BIN := declpac
+BUILD_DIR := bin
+BUILD := $(BUILD_DIR)/$(BIN)
+PREFIX ?= /usr/local
+DESTDIR ?=
+
+STAGED_GO := $(shell git diff --cached --name-only --diff-filter=ACM | grep '\.go$$')
+STAGED_PKGS := $(shell echo "$(STAGED_GO)" | tr ' ' '\n' | xargs -I{} dirname {} | sort -u | sed 's|^|./|')
+
+build:
+	@mkdir -p $(BUILD_DIR)
+	go build -o $(BUILD) ./cmd/declpac
+
+fmt:
+	@gofmt -w cmd pkg
+
+fmtcheck:
+	@if [ -z "$(STAGED_GO)" ]; then exit 0; fi; \
+	unformatted=$$(gofmt -l $(STAGED_GO)); \
+	if [ -n "$$unformatted" ]; then \
+		echo "$$unformatted: unformatted staged file"; \
+		exit 1; \
+	fi
+
+vet:
+	@if [ -z "$(STAGED_GO)" ]; then exit 0; fi; \
+	go vet $(STAGED_PKGS)
+
+check: fmtcheck vet
+
+githook:
+	@mkdir -p .git/hooks
+	@echo '#!/bin/sh' > .git/hooks/pre-commit
+	@echo 'make check' >> .git/hooks/pre-commit
+	@chmod +x .git/hooks/pre-commit
+	@echo "Installed pre-commit hook: .git/hooks/pre-commit"
+
+install: build
+	@mkdir -p $(DESTDIR)$(PREFIX)/bin
+	@install -m 0755 $(BUILD) $(DESTDIR)$(PREFIX)/bin/$(BIN)
+
+uninstall:
+	@rm -f $(DESTDIR)$(PREFIX)/bin/$(BIN)
@@ -1,9 +1,131 @@
 # declpac

-`declpac` syncs a declarative package list with the `pacman` package manager.
+Declarative package manager for Arch Linux that syncs your system with a declared package list using pacman.

-## Building
+## Features
+
+- Declarative state management — define your desired package list in files or stdin
+- Explicit package tracking — marks declared packages as explicit (with `--prune`)
+- Smart orphan cleanup — removes packages no longer needed (with `--prune`)
+- AUR support — builds and installs AUR packages automatically
+- Machine-readable output — perfect for scripting
+
+## Installation
+
+### Build from Source
+
+```bash
+git clone https://github.com/Riyyi/declpac.git
+cd declpac
+go build -o declpac ./cmd/declpac
+sudo mv declpac /usr/local/bin/
+```

 ### Dependencies

- go
+- Go 1.21+
+- pacman
+- makepkg (for AUR support)
+- git (for AUR support)
+- sudo/doas (root privileges)
+
+## Usage
+
+```bash
+# Single state file
+declpac --state packages.txt
+
+# Multiple state files
+declpac --state base.txt --state apps.txt
+
+# From stdin
+cat packages.txt | declpac
+
+# Preview changes without applying
+declpac --dry-run --state packages.txt
+```
+
+### State File Format
+
+One package name per line, lines beginning with `#` are comments:
+
+```
+bash
+vim
+git
+docker
+# this is a comment
+```
+
+### Implicit State File
+
+If `$XDG_CONFIG_HOME/declpac` (or `~/.config/declpac` on fallback) exists, its
+contents are automatically included in the package list.
+
+### Options
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--state` | `-s` | State file(s) to read package list from (can be used multiple times) |
+| `--nocheck` | | Skip safety check (allow significant package count reductions) |
+| `--dry-run` | | Preview changes without applying them |
+| `--prune` | | Mark packages as explicit and cleanup orphans |
+| `--verbose` | `-v` | Enable verbose output |
+| `--help` | `-h` | Show help message |
+
+## How It Works
+
+1. **Read** — Collect packages from all state files and stdin
+2. **Merge** — Combine into single package list
+3. **Categorize** — Check if packages are in official repos or AUR
+4. **Sync** — Install/update packages via pacman
+5. **Build** — Build and install AUR packages via makepkg
+6. **Mark** (with `--prune`) — Mark declared packages as explicit, all others as dependencies
+7. **Cleanup** (with `--prune`) — Remove orphaned packages
+
+### Database Freshness
+
+If the pacman database is older than 24 hours, it is automatically refreshed.
+
+### Logging
+
+Operation are logged to `$XDG_STATE_HOME/declpac.log`
+(or `~/.local/state/declpac.log` on fallback)
+
+## Troubleshooting
+
+### Package not found
+
+Check if the package exists:
+```bash
+pacman -Ss <package>
+```
+
+### Database sync fails
+
+```bash
+sudo pacman -Syy
+```
+
+## File Structure
+
+```
+declpac/
+├── cmd/declpac/
+│   └── main.go         # Entry point
+├── pkg/
+│   ├── input/          # State file/stdin reading
+│   ├── fetch/          # Package resolution
+│   │   ├── aur/        # AUR support
+│   │   └── alpm/       # ALPM support
+│   ├── pacman/         # Pacman operations
+│   │   ├── read/       # Read packages
+│   │   └── sync/       # Sync packages
+│   ├── log/            # Logging
+│   └── output/         # Output formatting
+└── README.md
+```
+
+## License
+
+GPL-3.0
@@ -0,0 +1,118 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/urfave/cli/v3"
+
+	"github.com/Riyyi/declpac/pkg/auth"
+	"github.com/Riyyi/declpac/pkg/input"
+	"github.com/Riyyi/declpac/pkg/log"
+	"github.com/Riyyi/declpac/pkg/output"
+	"github.com/Riyyi/declpac/pkg/pacman"
+	"github.com/Riyyi/declpac/pkg/pacman/read"
+)
+
+type Config struct {
+	StateFiles []string
+	NoCheck    bool
+	DryRun     bool
+	Prune      bool
+	Verbose    bool
+}
+
+func main() {
+	cfg := &Config{}
+
+	cmd := &cli.Command{
+		Name:  "declpac",
+		Usage: "Declarative pacman package manager",
+		Flags: []cli.Flag{
+			&cli.StringSliceFlag{
+				Name:        "state",
+				Aliases:     []string{"s"},
+				Usage:       "State file(s) to read package list from",
+				Destination: &cfg.StateFiles,
+			},
+			&cli.BoolFlag{
+				Name:        "nocheck",
+				Usage:       "Skip safety check",
+				Destination: &cfg.NoCheck,
+			},
+			&cli.BoolFlag{
+				Name:        "dry-run",
+				Usage:       "Simulate the sync without making changes",
+				Destination: &cfg.DryRun,
+			},
+			&cli.BoolFlag{
+				Name:        "prune",
+				Usage:       "Mark packages and cleanup orphans",
+				Destination: &cfg.Prune,
+			},
+			&cli.BoolFlag{
+				Name:        "verbose",
+				Aliases:     []string{"v"},
+				Usage:       "Enable verbose output",
+				Destination: &cfg.Verbose,
+			},
+		},
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			log.Verbose = cfg.Verbose
+			return run(cfg)
+		},
+	}
+
+	if err := cmd.Run(context.Background(), os.Args); err != nil {
+		os.Exit(1)
+	}
+}
+
+func run(cfg *Config) error {
+	start := time.Now()
+	log.Debug("run: starting...")
+
+	packages, err := input.ReadPackages(cfg.StateFiles)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return err
+	}
+	log.Debug("run: packages read (%.2fs)", time.Since(start).Seconds())
+
+	merged, err := input.Merge(packages)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return err
+	}
+
+	if cfg.DryRun {
+		result, err := read.DryRun(merged)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error: %v\n", err)
+			return err
+		}
+		fmt.Println(output.Format(result))
+		log.Debug("run: dry-run done (%.2fs)", time.Since(start).Seconds())
+		return nil
+	}
+
+	auth.Start()
+
+	if err := log.OpenLog(); err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return err
+	}
+	defer log.Close()
+
+	result, err := pacman.Sync(merged, cfg.NoCheck, cfg.Prune)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return err
+	}
+
+	fmt.Println(output.Format(result))
+	log.Debug("run: sync done (%.2fs)", time.Since(start).Seconds())
+	return nil
+}
@@ -2,8 +2,8 @@ module github.com/Riyyi/declpac

 go 1.26.2

-require (
-	github.com/Jguer/aur v1.3.0 // indirect
-	github.com/Jguer/dyalpm v0.1.2 // indirect
-	github.com/ebitengine/purego v0.10.0 // indirect
-)
+require github.com/urfave/cli/v3 v3.8.0
+
+require github.com/Jguer/dyalpm v0.1.2
+
+require github.com/ebitengine/purego v0.10.0 // indirect
@@ -1,6 +1,14 @@
-github.com/Jguer/aur v1.3.0 h1:skdjp/P9kB75TBaJmn9PKK/kCeA9QsgjdUrORZ3gldU=
-github.com/Jguer/aur v1.3.0/go.mod h1:F8Awo+WKzTxlXtNOO4pDQjMkePLZ+oMSbu+1fKLTTLo=
 github.com/Jguer/dyalpm v0.1.2 h1:Gl0+GDWBQmo3DSsfzTPnKqCwYqcroq0j6kAtsIUkpUw=
 github.com/Jguer/dyalpm v0.1.2/go.mod h1:FpcWwU1eYHVWMKmr/yHFqHYKsS+qGKCtk/FIXirj2MY=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
 github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/urfave/cli/v3 v3.8.0 h1:XqKPrm0q4P0q5JpoclYoCAv0/MIvH/jZ2umzuf8pNTI=
+github.com/urfave/cli/v3 v3.8.0/go.mod h1:ysVLtOEmg2tOy6PknnYVhDoouyC/6N42TMeoMzskhso=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-15
@@ -0,0 +1,46 @@
+## Implementation
+
+### Log File Location
+- Path: `/var/log/declpac.log`
+- Single merged log file (stdout + stderr intermingled in order of arrival)
+
+### State-Modifying Functions (need logging)
+1. `SyncPackages()` - `pacman -S --needed <packages>`
+2. `InstallAUR()` - `git clone` + `makepkg -si --noconfirm`
+3. `MarkAllAsDeps()` - `pacman -D --asdeps`
+4. `MarkAsExplicit()` - `pacman -D --asexplicit <packages>`
+5. `CleanupOrphans()` - `pacman -Rns`
+
+### Functions to Skip (read-only)
+- `DryRun()` - queries only
+- `getInstalledCount()` - pacman -Qq
+
+### Execution Patterns
+
+| Pattern | Functions | How |
+|---------|------------|-----|
+| Captured | All state-modifying functions | capture output, write to log with single timestamp at start, write to terminal |
+
+### One Timestamp Per Tool Call
+Instead of streaming with MultiWriter (multiple timestamps), each state-modifying function:
+1. Writes timestamp + operation name to log
+2. Runs command, captures output
+3. Writes captured output to log
+4. Writes output to terminal
+
+This ensures exactly 1 timestamp print per tool call.
+
+### Error Handling
+- Write error to log BEFORE returning from function
+- Print error to stderr so user sees it
+
+### Dependencies
+- Add to imports: `os`, `path/filepath`
+
+### Flow in Sync() or main entrypoint
+1. Call `OpenLog()` at program start, defer close
+2. Each state-modifying function calls `state.Write()` with timestamp prefix
+
+### Wire into main.go
+- Open log at start of `run()`
+- Pass log writer to pacman package (via exported function or global)
@@ -0,0 +1,26 @@
+## Why
+
+The tool exits without saving the full pacman output, making debugging difficult
+when operations fail. Users need a persistent log of all pacman operations for
+debugging and audit.
+
+## What Changes
+
+- Add state directory initialization creating `~/.local/state/declpac` if not exists
+- Open/manage a single log file at `/var/log/declpac.log`
+- Instrument all state-modifying exec calls in `pkg/pacman/pacman.go` to tee or append output to this file
+- Skip debug messages (internal timing logs)
+- Capture and write errors before returning
+
+## Capabilities
+
+### New Capabilities
+- Operation logging: Persist stdout/stderr from all pacman operations
+
+### Modified Capabilities
+- None
+
+## Impact
+
+- `pkg/pacman/pacman.go`: Instrument all state-modifying functions to write to log file
+- New module: May create `pkg/state/state.go` or similar for log file management
@@ -0,0 +1,41 @@
+## Tasks
+
+- [x] 1. Create state module
+
+Create `pkg/state/state.go`:
+- `OpenLog()` - opens `/var/log/declpac.log` in append mode
+- `GetLogWriter()` - returns the raw log file writer (for MultiWriter)
+- `Write(msg []byte)` - writes message with timestamp + dashes separator
+- `Close()` - closes the file
+
+- [x] 2. Wire into main.go
+
+In `cmd/declpac/main.go` `run()`:
+- Call `OpenLog()` at start
+- `defer Close()` log
+
+- [x] 3. Instrument pkg/pacman
+
+Modify `pkg/pacman/pacman.go`:
+
+Each state-modifying function writes timestamp ONCE at start, then captures output:
+- Write `timestamp - operation name` to log
+- Run command, capture output
+- Write captured output to log
+- Write output to terminal
+
+**Functions updated:**
+- `SyncPackages()` - write output with timestamp
+- `CleanupOrphans()` - write output with timestamp
+- `MarkAllAsDeps()` - write operation name with timestamp before running
+- `MarkAsExplicit()` - write operation name with timestamp before running
+- `InstallAUR()` - write "Cloning ..." and "Building package..." with timestamps
+- Error handling - `state.Write([]byte("error: ..."))` for all error paths
+
+- [x] 4. Add io import
+
+Add `io` to imports in pacman.go
+
+- [x] 5. Test
+
+Run a sync operation and verify log file created at `/var/log/declpac.log`
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-14
@@ -0,0 +1,137 @@
+## Context
+
+Currently, `pkg/pacman/pacman.go` uses subprocess calls to query pacman for package existence:
+- `pacman -Qip <pkg>` to check local DB (per package)
+- `pacman -Sip <pkg>` to check sync repos (per package)
+
+For n packages, this spawns 2n subprocesses (up to ~300 for typical package lists). Each subprocess has fork/exec overhead, making this the primary performance bottleneck.
+
+The AUR queries are already batched (single HTTP POST with all package names), which is the desired pattern.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Eliminate subprocess overhead for local/sync DB package lookups
+- Maintain batched AUR HTTP calls (single request per batch)
+- Track installed status per package in PackageInfo
+- Provide dry-run output showing exact packages to install/remove
+- Handle orphan cleanup correctly
+
+**Non-Goals:**
+- Parallel AUR builds (still sequential)
+- Custom pacman transaction handling (use system pacman)
+- Repository configuration changes
+- Package download/compile optimization
+
+## Decisions
+
+### 1. Use Jguer/dyalpm for DB access
+
+**Decision**: Use `github.com/Jguer/dyalpm` library instead of spawning subprocesses.
+
+**Rationale**:
+- Direct libalpm access (same backend as pacman)
+- Already Go-native with proper type safety
+- Supports batch operations via `GetPkgCache()` and `PkgCache()` iterators
+
+**Alternatives considered**:
+- Parse `pacman -Qs` output - fragile, still subprocess-based
+- Write custom libalpm bindings - unnecessary effort
+
+### 2. Single-pass package resolution algorithm
+
+**Decision**: Process all packages through local DB → sync DBs → AUR in one pass.
+
+```
+For each package in collected state:
+  1. Check local DB (batch lookup) → if found, mark Installed=true
+  2. If not local, check all sync DBs (batch lookup per repo)
+  3. If not in sync, append to AUR batch
+
+Batch query AUR with all remaining packages
+Throw error if any package not found in local/sync/AUR
+
+Collect installed status from local DB
+(Perform sync operations - skip in dry-run)
+(Mark ALL currently installed packages as deps - skip in dry-run)
+(Then mark collected state packages as explicit - skip in dry-run)
+(Cleanup orphans - skip in dry-run)
+Output summary
+```
+
+**Rationale**:
+- Single iteration over packages
+- Batch DB lookups minimize libalpm calls
+- Clear error handling for missing packages
+- Consistent with existing behavior
+
+### 3. Batch local/sync DB lookup implementation
+
+**Decision**: For local DB, iterate `localDB.PkgCache()` once and build a map. For sync DBs, iterate each repo's `PkgCache()`.
+
+**Implementation**:
+```go
+// Build local package map in one pass
+localPkgs := make(map[string]bool)
+localDB.PkgCache().ForEach(func(pkg alpm.Package) error {
+    localPkgs[pkg.Name()] = true
+    return nil
+})
+
+// Similarly for each sync DB
+for _, syncDB := range syncDBs {
+    syncDB.PkgCache().ForEach(...)
+}
+```
+
+**Rationale**:
+- O(n) iteration where n = total packages in DB (not n queries)
+- Single map construction, O(1) lookups per state package
+- libalpm iterators are already lazy, no additional overhead
+
+### 4. Dry-run behavior
+
+**Decision**: Dry-run outputs exact packages that would be installed/removed without making any system changes.
+
+**Implementation**:
+- Skip `pacman -Syu` call
+- Skip `pacman -D --asdeps` (mark all installed as deps)
+- Skip `pacman -D --asexplicit` (mark state packages as explicit)
+- Skip `pacman -Rns` orphan cleanup
+- Still compute what WOULD happen for output
+
+**Note on marking strategy**:
+Instead of diffing between before/after installed packages, we simply:
+1. After sync completes, run `pacman -D --asdeps` on ALL currently installed packages (this marks everything as deps)
+2. Then run `pacman -D --asexplicit` on the collected state packages (this overrides them to explicit)
+
+This is simpler and achieves the same result.
+
+## Risks / Trade-offs
+
+1. **[Risk]** dyalpm initialization requires root privileges
+   - **[Mitigation]** This is same as pacman itself; if user can't run pacman, declpac won't work
+
+2. **[Risk]** libalpm state becomes stale if another pacman instance runs concurrently
+   - **[Mitigation]** Use proper locking, rely on pacman's own locking mechanism
+
+3. **[Risk]** AUR packages still built sequentially
+   - **[Acceptable]** Parallel AUR builds out of scope for this change
+
+4. **[Risk]** Memory usage for large package lists
+   - **[Mitigation]** Package map is ~100 bytes per package; 10k packages = ~1MB
+
+## Migration Plan
+
+1. Add `github.com/Jguer/dyalpm` to go.mod
+2. Refactor `ValidatePackage()` to use dyalpm instead of subprocesses
+3. Add `Installed bool` to `PackageInfo` struct
+4. Implement new resolution algorithm in `categorizePackages()`
+5. Update `Sync()` and `DryRun()` to use new algorithm
+6. Test with various package combinations
+7. Verify output matches previous behavior
+
+## Open Questions
+
+- **Q**: Should we also use dyalpm for `GetInstalledPackages()`?
+- **A**: Yes, can use localDB.PkgCache().Collect() or iterate - aligns with overall approach
@@ -0,0 +1,35 @@
+## Why
+
+The current pacman implementation spawns multiple subprocesses per package (pacman -Qip, pacman -Sip) to check if packages exist in local/sync DBs or AUR. With many packages, this creates significant overhead. Using the Jguer/dyalpm library provides direct libalpm access for batch queries, eliminating subprocess overhead while maintaining the batched AUR HTTP calls.
+
+## What Changes
+
+- **Add dyalpm dependency**: Integrate Jguer/dyalpm library for direct libalpm access
+- **Batch local DB check**: Use `localDB.PkgCache()` to check all packages at once instead of per-package `pacman -Qip`
+- **Batch sync DB check**: Use `syncDBs[i].PkgCache()` to check all sync repos at once instead of per-package `pacman -Sip`
+- **Enhance PackageInfo**: Add `Installed bool` field to track if package is already installed
+- **New algorithm**: Implement unified package resolution flow:
+  1. Batch check local DB for all packages
+  2. Batch check sync DBs for remaining packages
+  3. Batch query AUR for non-found packages
+  4. Track installed status throughout
+  5. Perform sync operations with proper marking
+  6. Output summary of changes
+
+## Capabilities
+
+### New Capabilities
+
+- `batch-package-resolution`: Unified algorithm that batch-resolves packages from local DB → sync DBs → AUR with proper installed tracking
+- `dry-run-simulation`: Shows exact packages that would be installed/removed without making changes
+
+### Modified Capabilities
+
+- None - this is a pure optimization with no behavior changes visible to users
+
+## Impact
+
+- **Code**: `pkg/pacman/pacman.go` - refactored to use dyalpm
+- **Dependencies**: Add Jguer/dyalpm to go.mod
+- **APIs**: `ValidatePackage()` signature changes (returns installed status)
+- **Performance**: O(n) subprocess calls → O(1) for local/sync DB checks
@@ -0,0 +1,72 @@
+## ADDED Requirements
+
+### Requirement: Batch package resolution from local, sync, and AUR databases
+The system SHALL resolve packages in a single pass through local DB → sync DBs → AUR using batch operations to minimize subprocess/API calls.
+
+#### Scenario: Package exists in local DB
+- **WHEN** a package from collected state exists in the local database
+- **THEN** the system SHALL mark it as found, set `Installed=true`, and exclude it from AUR queries
+
+#### Scenario: Package exists in sync DB
+- **WHEN** a package from collected state does NOT exist in local DB but exists in ANY enabled sync database
+- **THEN** the system SHALL mark it as found, set `Installed=false`, and exclude it from AUR queries
+
+#### Scenario: Package exists only in AUR
+- **WHEN** a package from collected state does NOT exist in local or sync databases but exists in AUR
+- **THEN** the system SHALL mark it as found with `InAUR=true`, set `Installed=false`, and use the cached AUR info
+
+#### Scenario: Package not found anywhere
+- **WHEN** a package from collected state is NOT in local DB, NOT in any sync DB, and NOT in AUR
+- **THEN** the system SHALL return an error listing the unfound package(s)
+
+#### Scenario: Batch AUR query
+- **WHEN** multiple packages need AUR lookup
+- **THEN** the system SHALL make a SINGLE HTTP request to AUR RPC with all package names (existing behavior preserved)
+
+### Requirement: Efficient local DB lookup using dyalpm
+The system SHALL use dyalpm's `PkgCache()` iterator to build a lookup map in O(n) time, where n is total packages in local DB, instead of O(n*m) subprocess calls.
+
+#### Scenario: Build local package map
+- **WHEN** initializing package resolution
+- **THEN** the system SHALL iterate localDB.PkgCache() once and store all package names in a map for O(1) lookups
+
+#### Scenario: Check package in local map
+- **WHEN** checking if a package exists in local DB
+- **THEN** the system SHALL perform an O(1) map lookup instead of spawning a subprocess
+
+### Requirement: Efficient sync DB lookup using dyalpm
+The system SHALL use each sync DB's `PkgCache()` iterator to check packages across all enabled repositories.
+
+#### Scenario: Check package in sync DBs
+- **WHEN** a package is not found in local DB
+- **THEN** the system SHALL check all enabled sync databases using their iterators
+
+#### Scenario: Package found in multiple sync repos
+- **WHEN** a package exists in more than one sync repository (e.g., core and community)
+- **THEN** the system SHALL use the first match found
+
+### Requirement: Track installed status in PackageInfo
+The system SHALL include an `Installed bool` field in `PackageInfo` to indicate whether the package is currently installed.
+
+#### Scenario: Package is installed
+- **WHEN** a package exists in the local database
+- **THEN** `PackageInfo.Installed` SHALL be `true`
+
+#### Scenario: Package is not installed
+- **WHEN** a package exists only in sync DB or AUR (not in local DB)
+- **THEN** `PackageInfo.Installed` SHALL be `false`
+
+### Requirement: Mark installed packages as deps, then state packages as explicit
+After package sync completes, the system SHALL mark all installed packages as dependencies, then override the collected state packages to be explicit. This avoids diffing before/after states.
+
+#### Scenario: Mark all installed as deps
+- **WHEN** package sync has completed (non-dry-run)
+- **THEN** the system SHALL run `pacman -D --asdeps` to mark ALL currently installed packages as dependencies
+
+#### Scenario: Override state packages to explicit
+- **WHEN** all installed packages have been marked as deps
+- **THEN** the system SHALL run `pacman -D --asexplicit` on the collected state packages, overriding their dependency status
+
+#### Scenario: Dry-run skips marking
+- **WHEN** operating in dry-run mode
+- **THEN** the system SHALL NOT execute any `pacman -D` marking operations
@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Dry-run shows packages to install without making changes
+In dry-run mode, the system SHALL compute what WOULD happen without executing any pacman operations.
+
+#### Scenario: Dry-run lists packages to install
+- **WHEN** dry-run is enabled and packages need to be installed
+- **THEN** the system SHALL populate `Result.ToInstall` with all packages that would be installed (both sync and AUR)
+
+#### Scenario: Dry-run lists packages to remove
+- **WHEN** dry-run is enabled and orphan packages exist
+- **THEN** the system SHALL populate `Result.ToRemove` with the list of orphan packages and `Result.Removed` with the count
+
+#### Scenario: Dry-run skips pacman sync
+- **WHEN** dry-run is enabled
+- **THEN** the system SHALL NOT execute `pacman -Syu` for package installation
+
+#### Scenario: Dry-run skips explicit/deps marking
+- **WHEN** dry-run is enabled
+- **THEN** the system SHALL NOT execute `pacman -D --asdeps` or `pacman -D --asexplicit`
+
+#### Scenario: Dry-run skips orphan cleanup
+- **WHEN** dry-run is enabled
+- **THEN** the system SHALL NOT execute `pacman -Rns` for orphan removal
+
+#### Scenario: Dry-run outputs count summary
+- **WHEN** dry-run is enabled
+- **THEN** the system SHALL still compute and output `Result.Installed` and `Result.Removed` counts as if the operations had run
@@ -0,0 +1,51 @@
+## 1. Setup
+
+- [x] 1.1 Add `github.com/Jguer/dyalpm` to go.mod
+- [x] 1.2 Run `go mod tidy` to fetch dependencies
+
+## 2. Core Refactoring
+
+- [x] 2.1 Update `PackageInfo` struct to add `Installed bool` field
+- [x] 2.2 Create `Pac` struct with `alpm.Handle` instead of just aurCache
+- [x] 2.3 Implement `NewPac()` that initializes alpm handle and local/sync DBs
+
+## 3. Package Resolution Algorithm
+
+- [x] 3.1 Implement `buildLocalPkgMap()` - iterate localDB.PkgCache() to create lookup map
+- [x] 3.2 Implement `checkSyncDBs()` - iterate each sync DB's PkgCache() to find packages
+- [x] 3.3 Implement `resolvePackages()` - unified algorithm:
+  - Step 1: Check local DB for all packages (batch)
+  - Step 2: Check sync DBs for remaining packages (batch per repo)
+  - Step 3: Batch query AUR for remaining packages
+  - Step 4: Return error if any package unfound
+  - Step 5: Track installed status from local DB
+
+## 4. Sync and DryRun Integration
+
+- [x] 4.1 Refactor `Sync()` function to use new resolution algorithm
+- [x] 4.2 Refactor `DryRun()` function to use new resolution algorithm
+- [x] 4.3 Preserve AUR batched HTTP calls (existing `fetchAURInfo`)
+- [x] 4.4 Preserve orphan cleanup logic (`CleanupOrphans()`)
+
+## 5. Marking Operations
+
+- [x] 5.1 Keep `MarkExplicit()` for marking state packages
+- [x] 5.2 After sync, run `pacman -D --asdeps` on ALL installed packages (simplifies tracking)
+- [x] 5.3 After deps marking, run `pacman -D --asexplicit` on collected state packages (overrides deps)
+- [x] 5.4 Skip marking operations in dry-run mode
+
+## 6. Cleanup and Output
+
+- [x] 6.1 Remove subprocess-based `ValidatePackage()` implementation
+- [x] 6.2 Remove subprocess-based `GetInstalledPackages()` implementation
+- [x] 6.3 Update output summary to show installed/removed counts
+- [x] 6.4 In dry-run mode, populate `ToInstall` and `ToRemove` lists
+
+## 7. Testing
+
+- [ ] 7.1 Test with packages in local DB only
+- [ ] 7.2 Test with packages in sync DBs only
+- [ ] 7.3 Test with AUR packages
+- [ ] 7.4 Test with missing packages (should error)
+- [ ] 7.5 Test dry-run mode output
+- [ ] 7.6 Test orphan detection and cleanup
@@ -77,7 +77,7 @@ package list, with all packages at their latest available versions.

 **AUR Integration**
 - First attempt: Try pacman -Syu for all packages (includes AUR auto-install if enabled)
- For packages not found in pacman repos: Check AUR via Jguer/aur library
+- For packages not found in pacman repos: Batch query AUR via info endpoint (single HTTP request for multiple packages)
 - If package in AUR: Build and install with makepkg (no AUR helpers)
 - AUR packages should also upgrade to latest version (no partial updates)
 - Clone AUR git repo to temp directory
@@ -110,10 +110,12 @@ package list, with all packages at their latest available versions.
 - Multiple --state flags allowed, all additive
 - Stdin input via standard input stream
 - No interactive prompts - fully automated
+- `--dry-run`: Simulate sync without making changes, print what would be installed/removed

 **Output Format**
 - Success: Print to stdout: `Installed X packages, removed Y packages`
 - No changes: Print `Installed 0 packages, removed 0 packages`
+- Dry-run: Print `Installed X packages, removed Y packages` with `Would install: ...` and `Would remove: ...` lines
 - Errors: Print error message to stderr
 - Exit codes: 0 for success, 1 for errors

@@ -19,6 +19,7 @@ list, ensuring all packages are at the latest version.
 - Machine-readable output (install/remove counts, exit codes)
 - No conflict resolution for missing packages (append-only)
 - Print error to stderr for empty state input and exit with code 1
+- Dry-run mode: simulate sync without making changes, show what would be installed/removed

 ## Capabilities

@@ -12,7 +12,7 @@ latest versions.

 #### Scenario: Fall back to AUR
 - **WHEN** package is not in pacman repositories but is in AUR
- **THEN** query AUR via Jguer/aur library
+- **THEN** batch query AUR via info endpoint (multiple packages in single request)
 - **AND** build and install with makepkg -si

 #### Scenario: Upgrade AUR packages
@@ -0,0 +1,49 @@
+# Dry-Run Mode
+
+## Summary
+
+Add `--dry-run` flag to simulate the sync operation without making any changes
+to the system. Shows what packages would be installed and what would be removed.
+
+## Motivation
+
+Users want to preview the effects of a sync operation before committing changes.
+This is useful for:
+- Verifying the intended changes are correct
+- Avoiding unintended package installations
+- Understanding what orphan cleanup will remove
+
+## Interface
+
+```
+declpac --dry-run --state packages.txt
+```
+
+## Behavior
+
+1. Read state files and stdin (same as normal mode)
+2. Validate packages exist (same as normal mode)
+3. Query current installed packages via `pacman -Qq`
+4. Compare declared packages to current state
+5. Identify packages that would be installed (not currently installed)
+6. Identify orphans that would be removed via `pacman -Qdtq`
+7. Output results with "Would install:" and "Would remove:" sections
+
+## Output Format
+
+```
+Installed 3 packages, removed 2 packages
+Would install: vim, git, docker
+Would remove: python2, perl-xml-parser
+```
+
+## Non-Goals
+
+- Actual package operations (no pacman -Syu, no pacman -Rns execution)
+- Package version comparison
+- Detailed dependency analysis
+
+## Trade-offs
+
+- Doesn't predict transitive dependencies that pacman might install
+- Orphan list may change after packages are installed
@@ -18,7 +18,6 @@ strategy without conflict resolution.
 - **WHEN** stdin contains packages not in state files
 - **THEN** those packages shall be added to the final state

-#### Scenario: Duplicate packages accumulate
+#### Scenario: Duplicate packages are deduplicated
 - **WHEN** the same package appears in multiple inputs
- **THEN** it shall be included multiple times in the final state (pacman
-  handles duplicates)
+- **THEN** it shall be included once in the final state (map deduplication)
@@ -17,7 +17,7 @@ After syncing, the system SHALL remove packages that are no longer required

 #### Scenario: Orphan cleanup after sync
 - **WHEN** sync operation completes successfully
- **THEN** system shall run pacman -Rsu to remove unneeded dependencies
+- **THEN** system shall run pacman -Rns to remove unneeded dependencies
 - **AND** report the number of packages removed

 #### Scenario: Orphan cleanup respects explicitly installed
@@ -10,7 +10,7 @@ The system SHALL execute pacman operations to install and upgrade all declared p

 #### Scenario: No partial upgrades
 - **WHEN** running pacman commands
- **THEN** system shall use -Syu flag (full system upgrade) ensuring all packages are latest
+- **THEN** system shall use -S --needed flag (sync with skip if up-to-date) ensuring declared packages are present

 #### Scenario: Package availability check
 - **WHEN** a package from input is not in pacman repositories
@@ -0,0 +1,104 @@
+## 1. Project Setup
+
+- [x] 1.1 Initialize Go module with proper imports
+- [x] 1.2 Add required dependencies (dyalpm wrapper, Jguer/aur)
+- [x] 1.3 Set up project structure (cmd/declpac/main.go, pkg/ subdirectory)
+- [x] 1.4 Add libalpm initialization and handle
+
+## 2. Input Parsing
+
+- [x] 2.1 Implement stdin reader to collect package names
+- [x] 2.2 Implement state file reader for text-list format
+- [x] 2.3 Add whitespace normalization for package names
+- [x] 2.4 Create package name set data structure
+
+## 3. Input Merging
+
+- [x] 3.1 Implement additive merging of stdin and state file packages
+- [x] 3.2 Handle multiple --state flags with last-writer-wins per file
+- [x] 3.3 Implement duplicate package handling (no deduplication)
+
+## 4. State Validation
+
+- [x] 4.1 Implement empty state detection (no packages found)
+- [x] 4.2 Add stderr error output for empty state
+- [x] 4.3 Set exit code 1 for empty state case (abort, not proceed)
+- [x] 4.4 Check pacman DB freshness (db.lock timestamp)
+- [x] 4.5 Run pacman -Syy if DB older than 1 day
+- [x] 4.6 Validate packages via libalpm (pacman repos)
+- [x] 4.7 Validate packages via Jguer/aur (AUR)
+- [x] 4.8 Fail fast with error if package not found
+
+## 5. Pacman Integration (Hybrid: query via libalpm, modify via exec)
+
+- [x] 5.1 Initialize libalpm handle for queries
+- [x] 5.2 Implement libalpm query for installed packages
+- [x] 5.3 Implement libalpm query for available packages
+- [x] 5.4 Implement pacman -Syy command execution (DB refresh)
+- [x] 5.5 Implement pacman -Syu command execution wrapper
+- [x] 5.6 Add command-line argument construction with package list
+- [x] 5.7 Capture pacman stdout and stderr output
+- [x] 5.8 Implement pacman error message parsing
+- [x] 5.9 Handle pacman exit codes for success/failure detection
+- [x] 5.10 Verify pacman automatically resolves transitive dependencies
+
+## 6. Explicit Marking & Orphan Cleanup
+
+- [x] 6.1 Get list of currently installed packages before sync
+- [x] 6.2 Mark declared state packages as explicitly installed via pacman -D --explicit
+- [x] 6.3 Run pacman sync operation (5.x series)
+- [x] 6.4 Run pacman -Rns to remove orphaned packages
+- [x] 6.5 Capture and report number of packages removed
+- [x] 6.6 Handle case where no orphans exist (no packages removed)
+
+## 7. AUR Integration
+
+- [x] 7.1 Implement AUR package lookup via Jguer/aur library
+- [x] 7.2 Check package not in pacman repos first (via libalpm)
+- [x] 7.3 Query AUR for missing packages
+- [x] 7.4 Implement AUR fallback using makepkg (direct build, not AUR helper)
+- [x] 7.5 Clone AUR package git repo to temp directory
+- [x] 7.6 Run makepkg -si in temp directory for installation
+- [x] 7.7 Upgrade existing AUR packages to latest (makepkg rebuild)
+- [x] 7.8 Add stderr error reporting for packages not in pacman or AUR
+- [x] 7.9 Capture makepkg stdout and stderr for output parsing
+- [x] 7.10 Handle makepkg exit codes for success/failure detection
+
+## 8. Output Generation
+
+- [x] 8.1 Parse pacman output for installed package count
+- [x] 8.2 Parse pacman output for removed package count (orphan cleanup)
+- [x] 8.3 Generate output: `Installed X packages, removed Y packages`
+- [x] 8.4 Handle 0 packages case: `Installed 0 packages, removed 0 packages`
+- [x] 8.5 Print errors to stderr
+- [x] 8.6 Set exit code 0 for success, 1 for errors
+
+## 9. CLI Interface
+
+- [x] 9.1 Implement --state flag argument parsing
+- [x] 9.2 Implement stdin input handling from /dev/stdin
+- [x] 9.3 Set up correct CLI usage/help message
+- [x] 9.4 Implement flag order validation
+
+## 10. Integration & Testing
+
+- [x] 10.1 Wire together stdin -> state files -> merging -> validation -> pacman sync -> orphan cleanup -> output
+- [x] 10.2 Test empty state error output and exit code 1
+- [x] 10.3 Test single state file parsing
+- [x] 10.4 Test multiple state file merging
+- [x] 10.5 Test stdin input parsing
+- [x] 10.6 Test explicit marking before sync
+- [x] 10.7 Test pacman command execution with real packages
+- [x] 10.8 Test orphan cleanup removes unneeded packages
+- [x] 10.9 Test AUR fallback with makepkg for AUR package
+- [x] 10.10 Test error handling for missing packages
+- [x] 10.11 Generate final binary
+
+## 11. Dry-Run Mode
+
+- [x] 11.1 Add --dry-run flag to CLI argument parsing
+- [x] 11.2 Implement DryRun function to query current state
+- [x] 11.3 Compare declared packages to current installations
+- [x] 11.4 Identify packages to install (not currently installed)
+- [x] 11.5 Identify orphans to remove via pacman -Qdtq
+- [x] 11.6 Output "Would install:" and "Would remove:" sections
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-17
@@ -0,0 +1,44 @@
+## Context
+
+Current `Resolve` in `pkg/fetch/fetch.go`:
+1. Initialize all packages with `Exists: true`
+2. Check local DB, set `Installed: true` if found
+3. Check sync DBs, set `Installed: false`
+4. Check AUR, set `InAUR: true`
+5. Error if not found anywhere
+
+Bug: wrong default + wrong order + conflates two concerns.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Fix Resolve algorithm to correctly classify packages
+- Separate "available" from "installed" concerns
+
+**Non-Goals:**
+- No new APIs or features
+- No refactoring outside Resolve function
+
+## Decisions
+
+**Decision 1: Start with Exists: false**
+- Default `Exists: false` (unknown) instead of `true`
+- Only set true when confirmed in sync DBs
+
+**Decision 2: Check sync DBs first**
+- Order: sync → local → AUR
+- First determine if package exists (anywhere)
+- Then determine if installed (local only)
+
+**Decision 3: Two-phase classification**
+
+| Phase | Check | Sets |
+|------|-------|-----|
+| 1. Availability | sync DBs | Exists: true/false |
+| 2. Installation | local DB | Installed: true/false |
+| 3. Fallback | AUR | InAUR: true if not in sync |
+
+## Risks / Trade-offs
+
+- Minimal risk: localized fix only
+- Trade-off: slight performance cost (check sync before local) - acceptable for correctness
@@ -0,0 +1,26 @@
+## Why
+
+The `Resolve` function in `pkg/fetch/fetch.go` has incorrect logic flow. It
+initializes all packages with `Exists: true`, then checks local DB first, then
+sync DBs, then AUR. This wrong order causes incorrect package state
+classification - packages that exist only in AUR may be incorrectly marked as
+found.
+
+## What Changes
+
+- Fix initialization: packages should start with `Exists: false` (unknown), not `true`
+- Fix order: check sync DBs BEFORE local DB to determine availability
+- Separate independent concerns: "available" (sync/AUR) from "installed" (local)
+- All packages must validate: either `Exists: true` or `InAUR: true`
+
+## Capabilities
+
+### New Capabilities
+- `package-resolve-logic`: Correct resolution algorithm for pacman packages
+
+### Modified Capabilities
+- None
+
+## Impact
+
+- `pkg/fetch/fetch.go`: `Resolve` function
@@ -0,0 +1,7 @@
+## 1. Fix Resolve Function Logic
+
+- [x] 1.1 Change initialization: start packages with Exists: false instead of true
+- [x] 1.2 Reorder to check sync DBs BEFORE local DB
+- [x] 1.3 Separate availability check (sync DBs) from installation check (local DB)
+- [x] 1.4 Add AUR fallback for packages not in sync DBs
+- [x] 1.5 Validate all packages have either Exists or InAUR before returning
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-14
@@ -0,0 +1,25 @@
+## Context
+
+The dyalpm library's `SyncDBs()` returns an empty slice because it doesn't automatically load sync databases from pacman.conf. This causes `resolvePackages()` to skip the sync DB search entirely and fall through to checking the AUR, which fails for official repo packages.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Register sync databases so `resolvePackages()` can find official repo packages
+
+**Non-Goals:**
+- Modify package installation logic
+- Add support for custom repositories
+
+## Decisions
+
+1. **Register each repo manually** - After `handle.SyncDBs()` returns empty, loop through known repos (core, extra, multilib) and call `handle.RegisterSyncDB()` for each.
+
+2. **Use hardcoded repo list** - Arch Linux standard repos are core, extra, multilib. This matches pacman.conf.
+
+3. **Silent failure for missing repos** - If a repo isn't configured in pacman.conf, `RegisterSyncDB` will return a valid but empty DB. Filter by checking if `PkgCache()` has any packages.
+
+## Risks / Trade-offs
+
+- Hardcoded repo names may need updating if Arch adds/removes standard repos → Low risk, rare change
+- Repo registration could fail silently → Mitigated by checking PkgCache count
@@ -0,0 +1,21 @@
+## Why
+
+The program fails to find packages that exist in official repositories (like `cmake` in `extra`). The dyalpm library's `SyncDBs()` returns an empty list, so the code never searches the sync databases and falls through to checking the AUR, which also doesn't have the package.
+
+## What Changes
+
+- Register sync databases manually after initializing the dyalpm handle
+- Loop through known repos (core, extra, multilib) and call `RegisterSyncDB` for each
+- Handle the case where a repo might not be configured in pacman.conf
+
+## Capabilities
+
+### New Capabilities
+- None - this is a bug fix to existing functionality
+
+### Modified Capabilities
+- None
+
+## Impact
+
+- `pkg/fetch/fetch.go`: Modify `New()` function to register sync DBs after getting them from the handle
@@ -0,0 +1,7 @@
+## ADDED Requirements
+
+No new requirements - this is a bug fix to existing package resolution functionality.
+
+## MODIFIED Requirements
+
+No modified requirements.
@@ -0,0 +1,10 @@
+## 1. Implement sync DB registration
+
+- [x] 1.1 Modify Pac struct to include a method for registering sync DBs
+- [x] 1.2 In New(), after getting empty syncDBs from handle, loop through ["core", "extra", "multilib"] and call RegisterSyncDB for each
+- [x] 1.3 Filter out repos that have no packages (not configured in pacman.conf)
+
+## 2. Test the fix
+
+- [x] 2.1 Run `./declpac --dry-run --state <(echo "cmake")` and verify it resolves cmake from extra repo
+- [x] 2.2 Test with other official repo packages (e.g., "git" from extra, "base" from core)
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-14
@@ -0,0 +1,141 @@
+# Design: Refactor pkg Into Modular Packages
+
+## New Structure
+
+```
+pkg/
+├── pacman/     # write operations only
+│   └── pacman.go
+├── fetch/     # package resolution (NEW)
+│   └── fetch.go
+├── validation/ # DB freshness (existing, expand)
+│   └── validation.go
+├── output/    # (unchanged)
+│   └── output.go
+├── merge/    # (unchanged)
+│   └── merge.go
+└── input/    # (unchanged)
+    └── input.go
+```
+
+## Package Responsibilities
+
+### pkg/fetch (NEW)
+
+```
+type Fetcher struct {
+    handle  dyalpm.Handle
+    localDB dyalpm.Database
+    syncDBs []dyalpm.Database
+    aurCache map[string]AURPackage
+}
+
+func New() *Fetcher
+func (f *Fetcher) Close() error
+func (f *Fetcher) Resolve(packages []string) (map[string]*PackageInfo, error)
+func (f *Fetcher) ListOrphans() ([]string, error)
+```
+
+Extracted from `pacman.go`:
+- `buildLocalPkgMap()`
+- `checkSyncDBs()`
+- `resolvePackages()`
+- AUR cache (`ensureAURCache()`, `fetchAURInfo()`)
+
+### pkg/pacman (REFACTORED)
+
+```
+func Sync(packages []string) (*output.Result, error)
+func DryRun(packages []string) (*output.Result, error)
+func MarkAsExplicit(packages []string) error
+func MarkAllAsDeps() error
+func CleanupOrphans() (int, error)
+```
+
+Write actions only:
+- `Sync()` - calls `Fetcher` for resolution, then pacman commands
+- `DryRun()` - calls `Fetcher.Resolve()` + `ListOrphans()`
+- `MarkAsExplicit()`, `MarkAllAsDeps()`
+- `CleanupOrphans()` - calls `ListOrphans()` then removes
+
+### pkg/validation (REFACTORED)
+
+```
+func CheckDBFreshness() error
+```
+
+Keep as-is: checks lock file age, auto-synces if stale.
+
+Remove from `pacman.go`:
+- `IsDBFresh()` - replaced by `CheckDBFreshness()`
+- `SyncDB()` - called by validation when stale
+
+### Orphan Deduplication
+
+```go
+// In fetch/fetch.go
+func (f *Fetcher) ListOrphans() ([]string, error) {
+    cmd := exec.Command("pacman", "-Qdtq")
+    // ...
+}
+
+// In pacman/pacman.go
+func CleanupOrphans() (int, error) {
+    orphans, err := fetcher.ListOrphans()  // reuse
+    if err != nil || len(orphans) == 0 {
+        return 0, nil
+    }
+    // ... remove
+}
+
+func DryRun(...) (*output.Result, error) {
+    orphans, err := fetcher.ListOrphans()  // reuse
+    // ...
+}
+```
+
+## Data Structures Move to fetch
+
+```go
+// In fetch/fetch.go
+type PackageInfo struct {
+    Name      string
+    InAUR     bool
+    Exists    bool
+    Installed bool
+    AURInfo   *AURPackage
+    syncPkg   dyalpm.Package
+}
+
+type AURResponse struct {
+    Results []AURPackage `json:"results"`
+}
+
+type AURPackage struct {
+    Name        string `json:"Name"`
+    PackageBase string `json:"PackageBase"`
+    Version     string `json:"Version"`
+    URL         string `json:"URL"`
+}
+```
+
+## Import Changes
+
+`pkg/pacman/fetch.go` will need:
+- `github.com/Jguer/dyalpm`
+- `github.com/Riyyi/declpac/pkg/output`
+
+`pkg/pacman/pacman.go` will need:
+- `github.com/Riyyi/declpac/pkg/fetch`
+- `github.com/Riyyi/declpac/pkg/output`
+
+## Dependencies to Add
+
+- New import: `pkg/fetch` in `pacman` package
+
+## No Changes To
+
+- CLI entry points
+- `output.Result` struct
+- `input.ReadPackages()`
+- `merge.Merge()`
@@ -0,0 +1,30 @@
+# Proposal: Refactor pkg Into Modular Packages
+
+## Summary
+
+Split monolithic `pkg/pacman/pacman.go` into focused packages: `fetch` (package resolution), `validation` (DB checks), and keep `pacman` for write actions only. Also deduplicate orphan detection logic.
+
+## Motivation
+
+`pacman.go` is 645 lines doing too much:
+- Package resolution (local + sync DBs + AUR)
+- DB freshness checks
+- Pacman write operations (sync, mark, clean)
+- Orphan listing/cleanup
+
+This violates single responsibility. Hard to test, reason about, or reuse. Also has duplication:
+- `validation.CheckDBFreshness()` and `pacman.IsDBFresh()` both check DB freshness
+- `listOrphans()` and `CleanupOrphans()` duplicate orphan detection
+
+## Scope
+
+- Extract package resolution to new `pkg/fetch/`
+- Move DB freshness to `pkg/validation/` (keep `CheckDBFreshness()`)
+- Keep only write actions in `pkg/pacman/`
+- Deduplicate orphan logic: one function for listing, reuse in cleanup and dry-run
+
+## Out of Scope
+
+- No new features
+- No API changes to CLI
+- No changes to `pkg/output/`, `pkg/merge/`, `pkg/input/`
@@ -0,0 +1,15 @@
+# Scope
+
+## In Scope
+
+- Extract package resolution from pacman.go to pkg/fetch
+- Deduplicate orphan listing
+- Keep pacman write operations in pacman package
+- Maintain existing CLI API
+
+## Out of Scope
+
+- New features
+- New package management backends (e.g., libalpm alternatives)
+- Config file changes
+- State file format changes
@@ -0,0 +1,38 @@
+# Tasks: Refactor pkg Into Modular Packages
+
+## Phase 1: Create pkg/fetch
+
+- [x] 1.1 Create `pkg/fetch/fetch.go`
+- [x] 1.2 Move `AURResponse`, `AURPackage`, `PackageInfo` structs to fetch
+- [x] 1.3 Move `buildLocalPkgMap()` to fetch as `Fetcher.buildLocalPkgMap()`
+- [x] 1.4 Move `checkSyncDBs()` to fetch as `Fetcher.checkSyncDBs()`
+- [x] 1.5 Move `resolvePackages()` to fetch as `Fetcher.Resolve()`
+- [x] 1.6 Move AUR cache methods (`ensureAURCache`, `fetchAURInfo`) to fetch
+- [x] 1.7 Add `New()` and `Close()` to Fetcher
+- [x] 1.8 Add `ListOrphans()` to Fetcher
+
+## Phase 2: Refactor pkg/pacman
+
+- [x] 2.1 Remove from pacman.go (now in fetch):
+  - `buildLocalPkgMap()`
+  - `checkSyncDBs()`
+  - `resolvePackages()`
+  - `ensureAURCache()`
+  - `fetchAURInfo()`
+  - `AURResponse`, `AURPackage`, `PackageInfo` structs
+- [x] 2.2 Remove `IsDBFresh()` and `SyncDB()` (use validation instead)
+- [x] 2.3 Update imports in pacman.go to include fetch package
+- [x] 2.4 Update `Sync()` to use `fetch.Fetcher` for resolution
+- [x] 2.5 Update `DryRun()` to call `fetcher.ListOrphans()` instead of duplicate call
+- [x] 2.6 Update `CleanupOrphans()` to call `fetcher.ListOrphans()` instead of duplicate call
+
+## Phase 3: Clean Up Validation
+
+- [x] 3.1 Keep `validation.CheckDBFreshness()` as-is
+- [x] 3.2 Remove any remaining DB freshness duplication
+
+## Phase 4: Verify
+
+- [x] 4.1 Run tests (if any exist)
+- [x] 4.2 Build: `go build ./...`
+- [x] 4.3 Verify CLI still works: test dry-run, sync, orphan cleanup
@@ -1,95 +0,0 @@
-## 1. Project Setup
-
- [ ] 1.1 Initialize Go module with proper imports
- [ ] 1.2 Add required dependencies (dyalpm wrapper, Jguer/aur)
- [ ] 1.3 Set up project structure (cmd/declpac/main.go, pkg/ subdirectory)
- [ ] 1.4 Add libalpm initialization and handle
-
-## 2. Input Parsing
-
- [ ] 2.1 Implement stdin reader to collect package names
- [ ] 2.2 Implement state file reader for text-list format
- [ ] 2.3 Add whitespace normalization for package names
- [ ] 2.4 Create package name set data structure
-
-## 3. Input Merging
-
- [ ] 3.1 Implement additive merging of stdin and state file packages
- [ ] 3.2 Handle multiple --state flags with last-writer-wins per file
- [ ] 3.3 Implement duplicate package handling (no deduplication)
-
-## 4. State Validation
-
- [ ] 4.1 Implement empty state detection (no packages found)
- [ ] 4.2 Add stderr error output for empty state
- [ ] 4.3 Set exit code 1 for empty state case (abort, not proceed)
- [ ] 4.4 Check pacman DB freshness (db.lock timestamp)
- [ ] 4.5 Run pacman -Syy if DB older than 1 day
- [ ] 4.6 Validate packages via libalpm (pacman repos)
- [ ] 4.7 Validate packages via Jguer/aur (AUR)
- [ ] 4.8 Fail fast with error if package not found
-
-## 5. Pacman Integration (Hybrid: query via libalpm, modify via exec)
-
- [ ] 5.1 Initialize libalpm handle for queries
- [ ] 5.2 Implement libalpm query for installed packages
- [ ] 5.3 Implement libalpm query for available packages
- [ ] 5.4 Implement pacman -Syy command execution (DB refresh)
- [ ] 5.5 Implement pacman -Syu command execution wrapper
- [ ] 5.6 Add command-line argument construction with package list
- [ ] 5.7 Capture pacman stdout and stderr output
- [ ] 5.8 Implement pacman error message parsing
- [ ] 5.9 Handle pacman exit codes for success/failure detection
- [ ] 5.10 Verify pacman automatically resolves transitive dependencies
-
-## 6. Explicit Marking & Orphan Cleanup
-
- [ ] 6.1 Get list of currently installed packages before sync
- [ ] 6.2 Mark declared state packages as explicitly installed via pacman -D --explicit
- [ ] 6.3 Run pacman sync operation (5.x series)
- [ ] 6.4 Run pacman -Rsu to remove orphaned packages
- [ ] 6.5 Capture and report number of packages removed
- [ ] 6.6 Handle case where no orphans exist (no packages removed)
-
-## 7. AUR Integration
-
- [ ] 7.1 Implement AUR package lookup via Jguer/aur library
- [ ] 7.2 Check package not in pacman repos first (via libalpm)
- [ ] 7.3 Query AUR for missing packages
- [ ] 7.4 Implement AUR fallback using makepkg (direct build, not AUR helper)
- [ ] 7.5 Clone AUR package git repo to temp directory
- [ ] 7.6 Run makepkg -si in temp directory for installation
- [ ] 7.7 Upgrade existing AUR packages to latest (makepkg rebuild)
- [ ] 7.8 Add stderr error reporting for packages not in pacman or AUR
- [ ] 7.9 Capture makepkg stdout and stderr for output parsing
- [ ] 7.10 Handle makepkg exit codes for success/failure detection
-
-## 8. Output Generation
-
- [ ] 8.1 Parse pacman output for installed package count
- [ ] 8.2 Parse pacman output for removed package count (orphan cleanup)
- [ ] 8.3 Generate output: `Installed X packages, removed Y packages`
- [ ] 8.4 Handle 0 packages case: `Installed 0 packages, removed 0 packages`
- [ ] 8.5 Print errors to stderr
- [ ] 8.6 Set exit code 0 for success, 1 for errors
-
-## 9. CLI Interface
-
- [ ] 9.1 Implement --state flag argument parsing
- [ ] 9.2 Implement stdin input handling from /dev/stdin
- [ ] 9.3 Set up correct CLI usage/help message
- [ ] 9.4 Implement flag order validation
-
-## 10. Integration & Testing
-
- [ ] 10.1 Wire together stdin -> state files -> merging -> validation -> pacman sync -> orphan cleanup -> output
- [ ] 10.2 Test empty state error output and exit code 1
- [ ] 10.3 Test single state file parsing
- [ ] 10.4 Test multiple state file merging
- [ ] 10.5 Test stdin input parsing
- [ ] 10.6 Test explicit marking before sync
- [ ] 10.7 Test pacman command execution with real packages
- [ ] 10.8 Test orphan cleanup removes unneeded packages
- [ ] 10.9 Test AUR fallback with makepkg for AUR package
- [ ] 10.10 Test error handling for missing packages
- [ ] 10.11 Generate final binary
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Package existence check via sync DBs
+
+When resolving packages, the system SHALL first check sync databases (core, extra, multilib) to determine if a package exists in official repositories. If found in sync DBs, `Exists` SHALL be set to true.
+
+#### Scenario: Package found in sync DB
+- **WHEN** package name exists in any sync database
+- **THEN** set `Exists: true`, `InAUR: false`
+
+#### Scenario: Package not found in sync DB
+- **WHEN** package name does not exist in any sync database
+- **THEN** keep `Exists: false` for further lookup
+
+### Requirement: Package installation check via local database
+
+After checking sync DBs, the system SHALL check the local package database to determine if a package is installed. This is independent of existence check.
+
+#### Scenario: Package installed locally
+- **WHEN** package is installed on the system
+- **THEN** set `Installed: true`
+
+#### Scenario: Package not installed locally
+- **WHEN** package is not installed on the system
+- **THEN** set `Installed: false`
+
+### Requirement: AUR fallback check
+
+If package is not found in sync DBs, the system SHALL check the AUR as a fallback.
+
+#### Scenario: Package found in AUR
+- **WHEN** package exists in AUR but not in sync DBs
+- **THEN** set `InAUR: true`
+
+#### Scenario: Package not found anywhere
+- **WHEN** package not in sync DBs, not in local DB, not in AUR
+- **THEN** return error "package not found"
+
+### Requirement: Validation at resolution end
+
+After all checks complete, the system SHALL ensure every package has either `Exists: true` or `InAUR: true`. No package SHALL leave the resolver in an ambiguous state.
+
+#### Scenario: All packages valid
+- **WHEN** all packages resolved successfully
+- **THEN** every package has Exists=true OR InAUR=true
@@ -0,0 +1,104 @@
+package auth
+
+import (
+	"fmt"
+	"os/exec"
+	"regexp"
+	"strconv"
+	"time"
+
+	"github.com/Riyyi/declpac/pkg/log"
+)
+
+var tool string
+var timeout time.Duration = 5 * time.Minute
+var refreshCommand []string = []string{"-n", "true"}
+
+// -----------------------------------------
+// public
+
+func Command(name string, args ...string) *exec.Cmd {
+	if tool == "" {
+		return log.Command(name, args...)
+	}
+	args = append([]string{name}, args...)
+	return log.Command(tool, args...)
+}
+
+func Run() {
+	exec.Command(tool, refreshCommand...).Run()
+}
+
+func Start() error {
+	err := detect()
+	if err != nil {
+		return err
+	}
+
+	// Automatically refresh privilege elevation to prevent user prompts
+	go func() {
+		for {
+			Run()
+			time.Sleep(timeout)
+		}
+	}()
+
+	return nil
+}
+
+// -----------------------------------------
+// private
+
+func detect() error {
+	tool = getTool()
+	if tool == "" {
+		return fmt.Errorf("no privilege elevation tool detected in PATH")
+	}
+
+	parseTimeout()
+	// We have to be a little faster than the actual timeout
+	timeout -= 30 * time.Second
+
+	return nil
+}
+
+func execLookPath(name string) string {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return ""
+	}
+	return path
+}
+
+func getTool() string {
+	sudo := execLookPath("sudo")
+	doas := execLookPath("doas")
+
+	if sudo != "" {
+		return "sudo"
+	}
+	if doas != "" {
+		return "doas"
+	}
+
+	return ""
+}
+
+func parseTimeout() {
+	switch tool {
+	case "sudo":
+		out, err := exec.Command("sudo", "sudo", "-V").CombinedOutput()
+		if err != nil {
+			return
+		}
+		re := regexp.MustCompile(`Authentication timestamp timeout: (\d+)\..*`)
+		matches := re.FindStringSubmatch(string(out))
+		if len(matches) == 2 {
+			if minutes, err := strconv.Atoi(matches[1]); err == nil {
+				timeout = time.Duration(minutes) * time.Minute
+			}
+		}
+	case "doas":
+		exec.Command("doas", "true").Run()
+	}
+}
@@ -0,0 +1,148 @@
+package alpm
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/Jguer/dyalpm"
+	"github.com/Riyyi/declpac/pkg/log"
+)
+
+var (
+	Root        = "/"
+	PacmanState = "/var/lib/pacman"
+)
+
+type Handle struct {
+	handle  dyalpm.Handle
+	localDB dyalpm.Database
+	syncDBs []dyalpm.Database
+}
+
+func (h *Handle) LocalPackages() (map[string]dyalpm.Package, error) {
+	start := time.Now()
+	log.Debug("LocalPackages: starting...")
+
+	localPkgs := make(map[string]dyalpm.Package)
+
+	err := h.localDB.PkgCache().ForEach(func(pkg dyalpm.Package) error {
+		localPkgs[pkg.Name()] = pkg
+		return nil
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to iterate local package cache: %w", err)
+	}
+
+	log.Debug("LocalPackages: done (%.2fs)", time.Since(start).Seconds())
+	return localPkgs, nil
+}
+
+func (h *Handle) FindProvidingPackage(depName string) (string, bool) {
+	pkg := h.handle.FindDBSatisfier(h.syncDBs, depName)
+	if pkg != nil {
+		return pkg.Name(), true
+	}
+	return "", false
+}
+
+func (h *Handle) Release() error {
+	if h.handle != nil {
+		h.handle.Release()
+	}
+	return nil
+}
+
+func (h *Handle) SyncPackages(pkgNames []string) (map[string]dyalpm.Package, error) {
+	start := time.Now()
+	log.Debug("SyncPackages: starting...")
+
+	syncPkgs := make(map[string]dyalpm.Package)
+	pkgSet := make(map[string]bool)
+	for _, name := range pkgNames {
+		pkgSet[name] = true
+	}
+
+	for _, db := range h.syncDBs {
+		err := db.PkgCache().ForEach(func(pkg dyalpm.Package) error {
+			if pkgSet[pkg.Name()] {
+				if _, exists := syncPkgs[pkg.Name()]; !exists {
+					syncPkgs[pkg.Name()] = pkg
+				}
+			}
+			return nil
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to iterate sync database %s: %w", db.Name(), err)
+		}
+	}
+
+	log.Debug("SyncPackages: done (%.2fs)", time.Since(start).Seconds())
+	return syncPkgs, nil
+}
+
+func New() (*Handle, error) {
+	start := time.Now()
+	log.Debug("alpm.New: starting...")
+
+	handle, err := dyalpm.Initialize(Root, PacmanState)
+	if err != nil {
+		return nil, fmt.Errorf("failed to initialize alpm: %w", err)
+	}
+
+	localDB, err := handle.LocalDB()
+	if err != nil {
+		handle.Release()
+		return nil, fmt.Errorf("failed to get local database: %w", err)
+	}
+
+	syncDBs, err := handle.SyncDBs()
+	if err != nil {
+		handle.Release()
+		return nil, fmt.Errorf("failed to get sync databases: %w", err)
+	}
+
+	if len(syncDBs) == 0 {
+		syncDBs, err = registerSyncDBs(handle)
+		if err != nil {
+			handle.Release()
+			return nil, fmt.Errorf("failed to register sync databases: %w", err)
+		}
+	}
+
+	log.Debug("alpm.New: done (%.2fs)", time.Since(start).Seconds())
+	return &Handle{
+		handle:  handle,
+		localDB: localDB,
+		syncDBs: syncDBs,
+	}, nil
+}
+
+// -----------------------------------------
+// private
+
+func registerSyncDBs(handle dyalpm.Handle) ([]dyalpm.Database, error) {
+	log.Debug("registerSyncDBs: starting...")
+
+	repos := []string{"core", "extra", "multilib"}
+	var dbs []dyalpm.Database
+
+	for _, repo := range repos {
+		db, err := handle.RegisterSyncDB(repo, 0)
+		if err != nil {
+			continue
+		}
+
+		count := 0
+		db.PkgCache().ForEach(func(pkg dyalpm.Package) error {
+			count++
+			return nil
+		})
+
+		if count > 0 {
+			dbs = append(dbs, db)
+		}
+	}
+
+	log.Debug("registerSyncDBs: done (%d dbs)", len(dbs))
+	return dbs, nil
+}
@@ -0,0 +1,100 @@
+package aur
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+
+	"github.com/Riyyi/declpac/pkg/log"
+)
+
+var AURInfoURL = "https://aur.archlinux.org/rpc?v=5&type=info"
+
+type Package struct {
+	Name        string   `json:"Name"`
+	PackageBase string   `json:"PackageBase"`
+	Version     string   `json:"Version"`
+	URL         string   `json:"URL"`
+	Depends     []string `json:"Depends"`
+	MakeDepends []string `json:"MakeDepends"`
+}
+
+func (p Package) AllDepends() []string {
+	return append(p.Depends, p.MakeDepends...)
+}
+
+type Response struct {
+	Results []Package `json:"results"`
+}
+
+type Client struct {
+	cache map[string]Package
+}
+
+func New() *Client {
+	return &Client{
+		cache: make(map[string]Package),
+	}
+}
+
+func (c *Client) Fetch(packages []string) (map[string]Package, error) {
+	start := time.Now()
+	log.Debug("aur.Fetch: starting...")
+
+	result := make(map[string]Package)
+
+	if len(packages) == 0 {
+		return result, nil
+	}
+
+	var uncached []string
+	for _, pkg := range packages {
+		if _, ok := c.cache[pkg]; !ok {
+			uncached = append(uncached, pkg)
+		}
+	}
+
+	if len(uncached) == 0 {
+		log.Debug("aur.Fetch: done (cached) (%.2fs)", time.Since(start).Seconds())
+		for _, pkg := range packages {
+			result[pkg] = c.cache[pkg]
+		}
+		return result, nil
+	}
+
+	v := url.Values{}
+	for _, pkg := range packages {
+		v.Add("arg[]", pkg)
+	}
+
+	resp, err := http.Get(AURInfoURL + "&" + v.Encode())
+	if err != nil {
+		return result, err
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return result, err
+	}
+
+	var aurResp Response
+	if err := json.Unmarshal(body, &aurResp); err != nil {
+		return result, err
+	}
+
+	for _, r := range aurResp.Results {
+		c.cache[r.Name] = r
+		result[r.Name] = r
+	}
+
+	log.Debug("aur.Fetch: done (%.2fs)", time.Since(start).Seconds())
+	return result, nil
+}
+
+func (c *Client) Get(name string) (Package, bool) {
+	pkg, ok := c.cache[name]
+	return pkg, ok
+}
@@ -0,0 +1,154 @@
+package fetch
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/Riyyi/declpac/pkg/fetch/alpm"
+	"github.com/Riyyi/declpac/pkg/fetch/aur"
+	"github.com/Riyyi/declpac/pkg/log"
+)
+
+type PackageInfo struct {
+	Name      string
+	InAUR     bool
+	Exists    bool
+	Installed bool
+	Provided  string
+	AURInfo   *aur.Package
+}
+
+type Fetcher struct {
+	alpmHandle *alpm.Handle
+	aurClient  *aur.Client
+}
+
+// -----------------------------------------
+// constructor
+
+func New() (*Fetcher, error) {
+	start := time.Now()
+	log.Debug("fetch.Fetcher New: starting...")
+
+	alpmHandle, err := alpm.New()
+	if err != nil {
+		return nil, err
+	}
+
+	aurClient := aur.New()
+
+	log.Debug("fetch.Fetcher New: done (%.2fs)", time.Since(start).Seconds())
+	return &Fetcher{
+		alpmHandle: alpmHandle,
+		aurClient:  aurClient,
+	}, nil
+}
+
+// -----------------------------------------
+// public
+
+func (f *Fetcher) BuildLocalPkgMap() (map[string]interface{}, error) {
+	localPkgs, err := f.alpmHandle.LocalPackages()
+	if err != nil {
+		return nil, err
+	}
+	result := make(map[string]interface{})
+	for k, v := range localPkgs {
+		result[k] = v
+	}
+	return result, nil
+}
+
+func (f *Fetcher) Close() error {
+	return f.alpmHandle.Release()
+}
+
+func (f *Fetcher) FetchAur(packages []string) (map[string]aur.Package, error) {
+	return f.aurClient.Fetch(packages)
+}
+
+func (f *Fetcher) FindProvidingPackage(depName string) (string, bool) {
+	return f.alpmHandle.FindProvidingPackage(depName)
+}
+
+func (f *Fetcher) GetAURPackage(name string) (aur.Package, bool) {
+	return f.aurClient.Get(name)
+}
+
+func (f *Fetcher) Resolve(packages []string) (map[string]*PackageInfo, error) {
+	start := time.Now()
+	log.Debug("fetch.Resolve: starting...")
+
+	result := make(map[string]*PackageInfo)
+	for _, pkg := range packages {
+		result[pkg] = &PackageInfo{Name: pkg, Exists: false}
+	}
+
+	syncPkgs, err := f.alpmHandle.SyncPackages(packages)
+	if err != nil {
+		return nil, err
+	}
+	log.Debug("fetch.Resolve: sync db check done (%.2fs)", time.Since(start).Seconds())
+
+	for pkg := range syncPkgs {
+		result[pkg].Exists = true
+		result[pkg].InAUR = false
+	}
+
+	localPkgs, err := f.alpmHandle.LocalPackages()
+	if err != nil {
+		return nil, err
+	}
+	log.Debug("fetch.Resolve: local pkgs built (%.2fs)", time.Since(start).Seconds())
+
+	for pkg := range localPkgs {
+		if info, ok := result[pkg]; ok {
+			info.Installed = true
+		}
+	}
+
+	var notInSync []string
+	for _, pkg := range packages {
+		if !result[pkg].Exists {
+			notInSync = append(notInSync, pkg)
+		}
+	}
+
+	if len(notInSync) > 0 {
+		if _, err := f.aurClient.Fetch(notInSync); err != nil {
+			log.Debug("fetch.Resolve: aur fetch error: %v", err)
+		}
+
+		for _, pkg := range packages {
+			info := result[pkg]
+			if info.Exists {
+				continue
+			}
+
+			if aurInfo, ok := f.aurClient.Get(pkg); ok {
+				info.InAUR = true
+				info.AURInfo = &aurInfo
+				continue
+			}
+
+			if providedBy, ok := f.FindProvidingPackage(pkg); ok {
+				log.Debug("fetch.Resolve: %s provided by %s", pkg, providedBy)
+				info.Provided = providedBy
+				info.Exists = true
+				continue
+			}
+
+			return nil, fmt.Errorf("package not found: %s", pkg)
+		}
+	}
+
+	for _, pkg := range packages {
+		info := result[pkg]
+		if !info.Exists && !info.InAUR {
+			return nil, fmt.Errorf("package not validated: %s", pkg)
+		}
+	}
+
+	log.Debug("fetch.Resolve: done (%.2fs)", time.Since(start).Seconds())
+	return result, nil
+}
@@ -0,0 +1,115 @@
+package input
+
+import (
+	"bufio"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/Riyyi/declpac/pkg/lib"
+)
+
+var ErrEmptyList = errors.New("package list is empty")
+
+// -----------------------------------------
+// public
+
+func Merge(packages map[string]bool) ([]string, error) {
+	result := make([]string, 0, len(packages))
+	for name := range packages {
+		result = append(result, name)
+	}
+	if len(result) == 0 {
+		return nil, ErrEmptyList
+	}
+	return result, nil
+}
+
+func ReadPackages(stateFiles []string) (map[string]bool, error) {
+	packages := make(map[string]bool)
+
+	for _, file := range stateFiles {
+		expanded := lib.ExpandPath(file)
+		if err := readStateFile(expanded, packages); err != nil {
+			return nil, err
+		}
+	}
+
+	implicitStateFile := getImplicitStateFile()
+	if fileExists(implicitStateFile) {
+		if err := readStateFile(implicitStateFile, packages); err != nil {
+			return nil, err
+		}
+	}
+
+	if err := readStdin(packages); err != nil {
+		return nil, err
+	}
+
+	return packages, nil
+}
+
+// -----------------------------------------
+// private
+
+func fileExists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+func getImplicitStateFile() string {
+	cfgDir := os.Getenv("XDG_CONFIG_HOME")
+	if cfgDir == "" {
+		cfgDir = "~/.config"
+	}
+	cfgDir = lib.ExpandPath(cfgDir)
+	return filepath.Join(cfgDir, "declpac")
+}
+
+func normalizePackageName(name string) string {
+	name = strings.TrimSpace(name)
+	if name == "" || strings.HasPrefix(name, "#") {
+		return ""
+	}
+	return name
+}
+
+func readStateFile(path string, packages map[string]bool) error {
+	file, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		name := normalizePackageName(scanner.Text())
+		if name != "" {
+			packages[name] = true
+		}
+	}
+
+	return scanner.Err()
+}
+
+func readStdin(packages map[string]bool) error {
+	info, err := os.Stdin.Stat()
+	if err != nil {
+		return err
+	}
+
+	if (info.Mode() & os.ModeCharDevice) != 0 {
+		return nil
+	}
+
+	scanner := bufio.NewScanner(os.Stdin)
+	for scanner.Scan() {
+		name := normalizePackageName(scanner.Text())
+		if name != "" {
+			packages[name] = true
+		}
+	}
+
+	return scanner.Err()
+}
@@ -0,0 +1,21 @@
+package lib
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// -----------------------------------------
+// public
+
+func ExpandPath(path string) string {
+	if strings.HasPrefix(path, "~/") {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return path
+		}
+		return filepath.Join(home, path[2:])
+	}
+	return path
+}
@@ -0,0 +1,74 @@
+package log
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/Riyyi/declpac/pkg/lib"
+)
+
+var logFile *os.File
+var Verbose bool
+
+// -----------------------------------------
+// public
+
+func Close() error {
+	if logFile == nil {
+		return nil
+	}
+	return logFile.Close()
+}
+
+func Command(name string, args ...string) *exec.Cmd {
+	cmdStr := name + " " + strings.Join(args, " ")
+	fmt.Fprintf(logFile, "[cmd] %s\n", cmdStr)
+	return exec.Command(name, args...)
+}
+
+func Debug(format string, args ...any) {
+	if !Verbose {
+		return
+	}
+	fmt.Fprintf(os.Stderr, "[debug] "+format+"\n", args...)
+}
+
+func GetLogWriter() io.Writer {
+	return logFile
+}
+
+func OpenLog() error {
+	stateDir := os.Getenv("XDG_STATE_HOME")
+	if stateDir == "" {
+		stateDir = "~/.local/state"
+	}
+	stateDir = lib.ExpandPath(stateDir)
+
+	logPath := filepath.Join(stateDir, "declpac.log")
+	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+	if err != nil {
+		return err
+	}
+
+	logFile = f
+	writeTimestamp()
+	return nil
+}
+
+func Write(msg []byte) {
+	logFile.Write(msg)
+}
+
+// -----------------------------------------
+// private
+
+func writeTimestamp() {
+	ts := time.Now().Format("2006-01-02 15:04:05")
+	header := fmt.Sprintf("\n--- %s ---\n", ts)
+	logFile.Write([]byte(header))
+}
@@ -0,0 +1,30 @@
+package output
+
+import (
+	"fmt"
+	"strings"
+)
+
+type Result struct {
+	Installed int
+	Removed   int
+	ToInstall []string
+	ToRemove  []string
+}
+
+// -----------------------------------------
+// public
+
+func Format(r *Result) string {
+	var b strings.Builder
+	b.WriteString(fmt.Sprintf("installed %d packages, removed %d packages", r.Installed, r.Removed))
+	if len(r.ToInstall) > 0 {
+		b.WriteString("\nwould install: ")
+		b.WriteString(strings.Join(r.ToInstall, ", "))
+	}
+	if len(r.ToRemove) > 0 {
+		b.WriteString("\nwould remove: ")
+		b.WriteString(strings.Join(r.ToRemove, ", "))
+	}
+	return b.String()
+}
@@ -0,0 +1,217 @@
+package pacman
+
+import (
+	"fmt"
+	"os"
+	"slices"
+	"time"
+
+	"github.com/Riyyi/declpac/pkg/fetch"
+	"github.com/Riyyi/declpac/pkg/log"
+	"github.com/Riyyi/declpac/pkg/output"
+	"github.com/Riyyi/declpac/pkg/pacman/read"
+	"github.com/Riyyi/declpac/pkg/pacman/sync"
+)
+
+func Sync(packages []string, noCheck bool, prune bool) (*output.Result, error) {
+	start := time.Now()
+	log.Debug("Sync: starting...")
+
+	explicitList, err := read.ExplicitList()
+	if err != nil {
+		return nil, err
+	}
+	explicitCount := len(explicitList)
+
+	if !noCheck && len(packages) < explicitCount/2 {
+		errMsg := "safety check: state packages (%d) less than half of explicitly installed (%d), override with --nocheck"
+		return nil, fmt.Errorf(errMsg, len(packages), explicitCount)
+	}
+
+	list, err := read.List()
+	if err != nil {
+		return nil, err
+	}
+	before := len(list)
+
+	fresh, err := read.DBFreshness()
+	if err != nil {
+		return nil, err
+	}
+	if !fresh {
+		if err := sync.RefreshDB(log.GetLogWriter()); err != nil {
+			return nil, err
+		}
+	}
+	log.Debug("Sync: database fresh (%.2fs)", time.Since(start).Seconds())
+
+	f, err := fetch.New()
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	log.Debug("Sync: initialized fetcher (%.2fs)", time.Since(start).Seconds())
+
+	log.Debug("Sync: categorizing packages...")
+	pacmanPkgs, aurPkgs, err := categorizePackages(f, packages)
+	if err != nil {
+		return nil, err
+	}
+	log.Debug("Sync: packages categorized (%.2fs)", time.Since(start).Seconds())
+
+	if len(pacmanPkgs) > 0 {
+		log.Debug("Sync: syncing %d pacman packages...", len(pacmanPkgs))
+		if err := sync.SyncPackages(pacmanPkgs, log.GetLogWriter()); err != nil {
+			return nil, err
+		}
+		log.Debug("Sync: pacman packages synced (%.2fs)", time.Since(start).Seconds())
+	}
+
+	for _, pkg := range aurPkgs {
+		if slices.Contains(list, pkg) {
+			continue
+		}
+		log.Debug("Sync: installing AUR package %s...", pkg)
+		aurInfo, ok := f.GetAURPackage(pkg)
+		if !ok {
+			return nil, fmt.Errorf("AUR package not found in cache: %s", pkg)
+		}
+		if err := sync.InstallAUR(f, pkg, aurInfo.PackageBase, false, log.GetLogWriter()); err != nil {
+			return nil, err
+		}
+		log.Debug("Sync: AUR package %s installed (%.2fs)", pkg, time.Since(start).Seconds())
+	}
+
+	var removed int
+	if prune {
+		log.Debug("Sync: running prune sanity check...")
+		if err := pruneSanityCheck(packages); err != nil {
+			return nil, err
+		}
+		log.Debug("Sync: prune sanity check passed (%.2fs)", time.Since(start).Seconds())
+
+		log.Debug("Sync: marking all as deps...")
+		if err := markAllAsDeps(); err != nil {
+			return nil, err
+		}
+		log.Debug("Sync: all marked as deps (%.2fs)", time.Since(start).Seconds())
+
+		log.Debug("Sync: marking state packages as explicit...")
+		if err := sync.MarkAs(packages, "explicit", log.GetLogWriter()); err != nil {
+			fmt.Fprintf(os.Stderr, "warning: could not mark state packages as explicit: %v\n", err)
+		}
+		log.Debug("Sync: state packages marked as explicit (%.2fs)", time.Since(start).Seconds())
+
+		removed, err = cleanupOrphans()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	list, _ = read.List()
+	if err != nil {
+		return nil, err
+	}
+	after := len(list)
+
+	installedCount := max(after-before, 0)
+
+	log.Debug("Sync: done (%.2fs)", time.Since(start).Seconds())
+	return &output.Result{
+		Installed: installedCount,
+		Removed:   removed,
+	}, nil
+}
+
+// -----------------------------------------
+// private
+
+func categorizePackages(f *fetch.Fetcher, packages []string) (pacmanPkgs, aurPkgs []string, err error) {
+	start := time.Now()
+	log.Debug("categorizePackages: starting...")
+
+	resolved, err := f.Resolve(packages)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	for _, pkg := range packages {
+		info := resolved[pkg]
+		if info == nil || (!info.Exists && !info.InAUR) {
+			fmt.Fprintf(os.Stderr, "error: package not found: %s\n", pkg)
+			continue
+		}
+		if info.InAUR {
+			aurPkgs = append(aurPkgs, pkg)
+		} else {
+			pacmanPkgs = append(pacmanPkgs, pkg)
+		}
+	}
+
+	log.Debug("categorizePackages: done (%.2fs)", time.Since(start).Seconds())
+	return pacmanPkgs, aurPkgs, nil
+}
+
+func cleanupOrphans() (int, error) {
+	start := time.Now()
+	log.Debug("cleanupOrphans: starting...")
+
+	orphans, err := read.ListOrphans()
+	if err != nil {
+		log.Write([]byte(fmt.Sprintf("error: %v\n", err)))
+		return 0, err
+	}
+
+	removed, err := sync.RemoveOrphans(orphans, log.GetLogWriter())
+	if err != nil {
+		log.Write([]byte(fmt.Sprintf("error: %v\n", err)))
+		return 0, err
+	}
+
+	log.Debug("cleanupOrphans: done (%.2fs)", time.Since(start).Seconds())
+	return removed, nil
+}
+
+func markAllAsDeps() error {
+	start := time.Now()
+	log.Debug("markAllAsDeps: starting...")
+
+	packages, err := read.List()
+	if err != nil || len(packages) == 0 {
+		return fmt.Errorf("failed to list packages: %w", err)
+	}
+
+	if err := sync.MarkAs(packages, "deps", log.GetLogWriter()); err != nil {
+		log.Write([]byte(fmt.Sprintf("error: %v\n", err)))
+		return err
+	}
+
+	log.Debug("markAllAsDeps: done (%.2fs)", time.Since(start).Seconds())
+	return nil
+}
+
+// pruneSanityCheck checks if the installation of all state packages succeeded,
+// before attempting to do package marking and orphan cleanup.
+func pruneSanityCheck(statePackages []string) error {
+	start := time.Now()
+	log.Debug("pruneSanityCheck: starting...")
+
+	localPackages, err := read.List()
+	if err != nil {
+		return fmt.Errorf("failed to list local packages: %w", err)
+	}
+
+	var missing []string
+	for _, pkg := range statePackages {
+		if !slices.Contains(localPackages, pkg) {
+			missing = append(missing, pkg)
+		}
+	}
+
+	if len(missing) > 0 {
+		return fmt.Errorf("safety check: missing state packages: %v", missing)
+	}
+
+	log.Debug("pruneSanityCheck: done (%.2fs)", time.Since(start).Seconds())
+	return nil
+}
@@ -0,0 +1,149 @@
+package read
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"time"
+
+	"github.com/Riyyi/declpac/pkg/fetch"
+	"github.com/Riyyi/declpac/pkg/log"
+	"github.com/Riyyi/declpac/pkg/output"
+)
+
+var LockFile = "/var/lib/pacman/db.lock"
+
+func DBFreshness() (bool, error) {
+	info, err := os.Stat(LockFile)
+	if err != nil {
+		return false, nil
+	}
+
+	age := time.Since(info.ModTime())
+	return age <= 24*time.Hour, nil
+}
+
+func DryRun(packages []string) (*output.Result, error) {
+	start := time.Now()
+	log.Debug("DryRun: starting...")
+
+	f, err := fetch.New()
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	log.Debug("DryRun: initialized fetcher (%.2fs)", time.Since(start).Seconds())
+
+	resolved, err := f.Resolve(packages)
+	if err != nil {
+		return nil, err
+	}
+	log.Debug("DryRun: packages resolved (%.2fs)", time.Since(start).Seconds())
+
+	var toInstall []string
+	var aurPkgs []string
+	for _, pkg := range packages {
+		info := resolved[pkg]
+		if info == nil || (!info.Exists && !info.InAUR) {
+			return nil, fmt.Errorf("package not found: %s", pkg)
+		}
+		if info.InAUR && !info.Installed {
+			aurPkgs = append(aurPkgs, pkg)
+		} else if !info.Installed {
+			toInstall = append(toInstall, pkg)
+		}
+	}
+	log.Debug("DryRun: packages categorized (%.2fs)", time.Since(start).Seconds())
+
+	orphans, err := ListOrphans()
+	if err != nil {
+		return nil, err
+	}
+	log.Debug("DryRun: orphans listed (%.2fs)", time.Since(start).Seconds())
+
+	pkgSet := make(map[string]bool)
+	for _, p := range packages {
+		pkgSet[p] = true
+	}
+	var toRemove []string
+	for _, o := range orphans {
+		if !pkgSet[o] {
+			toRemove = append(toRemove, o)
+		}
+	}
+
+	log.Debug("DryRun: done (%.2fs)", time.Since(start).Seconds())
+	return &output.Result{
+		Installed: len(toInstall) + len(aurPkgs),
+		Removed:   len(toRemove),
+		ToInstall: append(toInstall, aurPkgs...),
+		ToRemove:  toRemove,
+	}, nil
+}
+
+func ExplicitList() ([]string, error) {
+	start := time.Now()
+	log.Debug("ExplicitList: starting...")
+
+	cmd := exec.Command("pacman", "-Qqe")
+	output, err := cmd.Output()
+	if err != nil {
+		return nil, err
+	}
+
+	list := strings.Split(strings.TrimSpace(string(output)), "\n")
+	if len(list) > 0 && list[0] == "" {
+		list = nil
+	}
+
+	log.Debug("ExplicitList: done (%.2fs)", time.Since(start).Seconds())
+	return list, nil
+}
+
+func List() ([]string, error) {
+	start := time.Now()
+	log.Debug("List: starting...")
+
+	cmd := exec.Command("pacman", "-Qq")
+	output, err := cmd.Output()
+	if err != nil {
+		return nil, err
+	}
+
+	list := strings.Split(strings.TrimSpace(string(output)), "\n")
+	if list[0] == "" {
+		list = nil
+	}
+
+	log.Debug("List: done (%.2fs)", time.Since(start).Seconds())
+	return list, nil
+}
+
+func ListOrphans() ([]string, error) {
+	start := time.Now()
+	log.Debug("ListOrphans: starting...")
+
+	cmd := exec.Command("pacman", "-Qdtq")
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+
+	output, err := cmd.Output()
+	if err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) && exitErr.ExitCode() == 1 && stderr.Len() == 0 {
+			return nil, nil
+		}
+		return nil, err
+	}
+
+	orphans := strings.Split(strings.TrimSpace(string(output)), "\n")
+	if len(orphans) > 0 && orphans[0] == "" {
+		orphans = orphans[1:]
+	}
+
+	log.Debug("ListOrphans: done (%.2fs)", time.Since(start).Seconds())
+	return orphans, nil
+}
@@ -0,0 +1,318 @@
+package sync
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"os/user"
+	"strings"
+	"time"
+
+	"github.com/Riyyi/declpac/pkg/auth"
+	"github.com/Riyyi/declpac/pkg/fetch"
+	"github.com/Riyyi/declpac/pkg/fetch/aur"
+	"github.com/Riyyi/declpac/pkg/log"
+)
+
+type Result struct {
+	Installed int
+	Removed   int
+}
+
+// -----------------------------------------
+// public
+
+func InstallAUR(f *fetch.Fetcher, pkgName string, packageBase string, asDeps bool, logWriter io.Writer) error {
+	start := time.Now()
+	log.Debug("InstallAUR: starting...")
+
+	if logWriter == nil {
+		logWriter = os.Stderr
+	}
+
+	aurInfo := getAURInfo(f, pkgName, packageBase)
+	if err := resolveAndInstallDeps(f, aurInfo, logWriter); err != nil {
+		return err
+	}
+
+	tmpDir := getTempDirName() + "/" + pkgName
+	if err := createTempDir(tmpDir); err != nil {
+		return err
+	}
+	defer os.RemoveAll(tmpDir)
+
+	if err := cloneRepo(packageBase, tmpDir, logWriter); err != nil {
+		return err
+	}
+	log.Debug("InstallAUR: cloned (%.2fs)", time.Since(start).Seconds())
+
+	if err := buildPackage(tmpDir, asDeps, logWriter); err != nil {
+		return err
+	}
+	log.Debug("InstallAUR: built (%.2fs)", time.Since(start).Seconds())
+
+	pkgFile, err := findPKGFile(pkgName, tmpDir)
+	if err != nil {
+		return fmt.Errorf("failed to find built package: %w", err)
+	}
+
+	if err := installBuiltPackage(pkgFile, logWriter); err != nil {
+		return err
+	}
+	log.Debug("InstallAUR: done (%.2fs)", time.Since(start).Seconds())
+
+	return nil
+}
+
+func MarkAs(packages []string, flag string, logWriter io.Writer) error {
+	if len(packages) == 0 {
+		return nil
+	}
+	start := time.Now()
+	flagName := map[string]string{"deps": "asdeps", "explicit": "asexplicit"}[flag]
+	log.Debug("MarkAs(%s): starting...", flag)
+
+	if logWriter == nil {
+		logWriter = os.Stderr
+	}
+
+	args := append([]string{"-D", "--" + flagName}, packages...)
+	cmd := auth.Command("pacman", args...)
+	cmd.Stdout = logWriter
+	cmd.Stderr = logWriter
+	err := cmd.Run()
+	if err != nil {
+		return fmt.Errorf("mark as %s failed: %w", flag, err)
+	}
+
+	log.Debug("MarkAs(%s): done (%.2fs)", flag, time.Since(start).Seconds())
+	return nil
+}
+
+func RefreshDB(logWriter io.Writer) error {
+	start := time.Now()
+	log.Debug("RefreshDB: starting...")
+
+	if logWriter == nil {
+		logWriter = os.Stderr
+	}
+
+	cmd := auth.Command("pacman", "-Syy")
+	cmd.Stdout = logWriter
+	cmd.Stderr = logWriter
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("failed to refresh pacman database: %w", err)
+	}
+
+	log.Debug("RefreshDB: done (%.2fs)", time.Since(start).Seconds())
+	return nil
+}
+
+func RemoveOrphans(orphans []string, logWriter io.Writer) (int, error) {
+	start := time.Now()
+	log.Debug("RemoveOrphans: starting...")
+
+	if logWriter == nil {
+		logWriter = os.Stderr
+	}
+
+	if len(orphans) == 0 {
+		log.Debug("RemoveOrphans: done (no orphans) (%.2fs)", time.Since(start).Seconds())
+		return 0, nil
+	}
+
+	args := make([]string, 0, 3+len(orphans))
+	args = append(args, "pacman", "-Rns", "--noconfirm")
+	args = append(args, orphans...)
+	removeCmd := auth.Command(args[0], args[1:]...)
+	removeCmd.Stdout = logWriter
+	removeCmd.Stderr = logWriter
+	err := removeCmd.Run()
+	if err != nil {
+		return 0, fmt.Errorf("remove orphans failed: %w", err)
+	}
+
+	count := len(orphans)
+
+	log.Debug("RemoveOrphans: done (%d) (%.2fs)", count, time.Since(start).Seconds())
+	return count, nil
+}
+
+func SyncPackages(packages []string, logWriter io.Writer) error {
+	start := time.Now()
+	log.Debug("SyncPackages: starting...")
+
+	if logWriter == nil {
+		logWriter = os.Stderr
+	}
+
+	args := append([]string{"-S", "--needed", "--noconfirm"}, packages...)
+	cmd := auth.Command("pacman", args...)
+	cmd.Stdout = logWriter
+	cmd.Stderr = logWriter
+	err := cmd.Run()
+	if err != nil {
+		return fmt.Errorf("pacman sync failed: %w", err)
+	}
+
+	log.Debug("SyncPackages: done (%.2fs)", time.Since(start).Seconds())
+	return nil
+}
+
+// -----------------------------------------
+// private
+
+func buildPackage(tmpDir string, asDeps bool, logWriter io.Writer) error {
+	makepkgArgs := []string{"-D", tmpDir, "-s", "--noconfirm"}
+	if asDeps {
+		makepkgArgs = append(makepkgArgs, "--asdeps")
+	}
+	makepkgCmd := log.Command("makepkg", makepkgArgs...)
+	makepkgCmd.Stdout = logWriter
+	makepkgCmd.Stderr = logWriter
+	if err := makepkgCmd.Run(); err != nil {
+		return fmt.Errorf("makepkg failed to build AUR package: %w", err)
+	}
+	return nil
+}
+
+func cloneRepo(packageBase string, tmpDir string, logWriter io.Writer) error {
+	cloneURL := "https://aur.archlinux.org/" + packageBase + ".git"
+	cloneCmd := log.Command("git", "clone", cloneURL, tmpDir)
+	cloneCmd.Stdout = logWriter
+	cloneCmd.Stderr = logWriter
+	if err := cloneCmd.Run(); err != nil {
+		return fmt.Errorf("failed to clone AUR repo: %w", err)
+	}
+	return nil
+}
+
+func createTempDir(tmpDir string) error {
+	if tmpDir == "" || tmpDir == "/" || !strings.HasPrefix(tmpDir, "/tmp") {
+		return fmt.Errorf("safety check: prevented malformed rm -rf call")
+	}
+
+	rmdirCmd := log.Command("rm", "-rf", tmpDir)
+	if err := rmdirCmd.Run(); err != nil {
+		return fmt.Errorf("failed to remove temp directory: %w", err)
+	}
+
+	mkdirCmd := log.Command("mkdir", "-p", tmpDir)
+	if err := mkdirCmd.Run(); err != nil {
+		return fmt.Errorf("failed to create temp directory: %w", err)
+	}
+
+	return nil
+}
+
+func findPKGFile(pkgName string, dir string) (string, error) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return "", err
+	}
+	for _, entry := range entries {
+		name := entry.Name()
+		if !strings.HasSuffix(name, ".pkg.tar.zst") && !strings.HasSuffix(name, ".pkg.tar.gz") {
+			continue
+		}
+		// Skip packages that do not start with the exact package name, ex: sunshine-bin -> sunshine
+		if !strings.HasPrefix(name, pkgName) {
+			continue
+		}
+		// Skip packages that provide a debug package, ex: sunshine-bin -> sunshine-debug
+		if strings.HasPrefix(name, pkgName+"-debug") {
+			continue
+		}
+		return strings.Join([]string{dir, name}, "/"), nil
+	}
+	return "", fmt.Errorf("no package file found in %s", dir)
+}
+
+func getAURInfo(f *fetch.Fetcher, pkgName string, packageBase string) *aur.Package {
+	if packageBase == "" {
+		return nil
+	}
+	info, ok := f.GetAURPackage(pkgName)
+	if !ok {
+		return nil
+	}
+	return &info
+}
+
+func getTempDirName() string {
+	user, err := user.Current()
+	if err != nil {
+		return "/tmp/declpac"
+	}
+
+	return "/tmp/declpac-" + user.Username
+}
+
+func installBuiltPackage(pkgFile string, logWriter io.Writer) error {
+	installCmd := auth.Command("pacman", "-U", "--noconfirm", pkgFile)
+	installCmd.Stdout = logWriter
+	installCmd.Stderr = logWriter
+	if err := installCmd.Run(); err != nil {
+		return fmt.Errorf("failed to install package: %w", err)
+	}
+	return nil
+}
+
+func resolveAndInstallDeps(f *fetch.Fetcher, aurInfo *aur.Package, logWriter io.Writer) error {
+	if aurInfo == nil {
+		return nil
+	}
+
+	depends := aurInfo.AllDepends()
+	if len(depends) == 0 {
+		return nil
+	}
+
+	resolved, err := f.Resolve(depends)
+	if err != nil {
+		return fmt.Errorf("failed to resolve dependencies: %w", err)
+	}
+
+	var repoDeps, aurDeps []string
+	for _, dep := range depends {
+		info := resolved[dep]
+		if info.Installed {
+			continue
+		}
+		pkg := dep
+		if info.Provided != "" {
+			pkg = info.Provided
+		}
+		if info.Exists {
+			repoDeps = append(repoDeps, pkg)
+		} else if info.InAUR {
+			aurDeps = append(aurDeps, pkg)
+		}
+	}
+
+	if len(repoDeps) > 0 {
+		if err := SyncPackages(repoDeps, logWriter); err != nil {
+			return fmt.Errorf("failed to install repo dependencies: %w", err)
+		}
+	}
+
+	if len(aurDeps) == 0 {
+		return nil
+	}
+
+	fetched, err := f.FetchAur(aurDeps)
+	if err != nil {
+		log.Debug("sync.resolveAndInstallDeps: aur fetch error: %v", err)
+	}
+	for _, dep := range aurDeps {
+		depInfo, ok := fetched[dep]
+		if !ok {
+			continue
+		}
+		if err := InstallAUR(f, dep, depInfo.PackageBase, true, logWriter); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
@@ -5,6 +5,12 @@
      "source": "JuliusBrussee/caveman",
      "sourceType": "github",
      "computedHash": "a818cdc41dcfaa50dd891c5cb5e5705968338de02e7e37949ca56e8c30ad4176"
+    },
+    "grill-me": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "skillPath": "skills/productivity/grill-me/SKILL.md",
+      "computedHash": "784f0dbb7403b0f00324bce9a112f715342777a0daee7bbb7385f9c6f0a170ea"
    }
  }
 }
Author	SHA1	Message	Date
AI BotandRiyyi	1159be59d0	Add safety check before package pruning Verifies all state packages are installed locally before running markAllAsDeps and orphan cleanup.	2026-05-04 23:28:58 +02:00
Riyyi	0fc0684801	Improve tarball selection when installing AUR packages	2026-05-04 22:47:07 +02:00
AI BotandRiyyi	bcddfd13e7	Also install repo dependencies when installing AUR packages	2026-05-04 21:13:25 +02:00
Riyyi	4472bbc2e9	Add grill-me skill	2026-05-04 20:25:43 +02:00
Riyyi	b371c74e9a	Make tool request elevated privileges on-demand	2026-05-03 23:04:34 +02:00
Riyyi	76b83437ac	Add safety check before rm -rf call	2026-05-03 22:17:51 +02:00
AI BotandRiyyi	b04869f0e1	Move log to user owned directory	2026-05-03 21:29:49 +02:00
AI BotandRiyyi	7c4b0eda8b	Apply coding conventions	2026-05-03 18:01:00 +02:00
AI BotandRiyyi	317d5f4be9	Cache sudo user to avoid repeated env lookups	2026-05-03 17:49:53 +02:00
AI BotandRiyyi	b13c9da7a1	Improve AUR with AUR dependency installations	2026-05-03 17:40:31 +02:00
AI BotandRiyyi	c8cdace4bf	Update Go file structure conventions in AGENTS.md	2026-05-03 15:48:00 +02:00
AI BotandRiyyi	31fad42ab3	Reorder functions to follow public-first convention	2026-05-03 15:40:07 +02:00
AI BotandRiyyi	db4e22a580	Add --prune flag for explicit marking and orphan cleanup	2026-05-03 15:10:54 +02:00
AI BotandRiyyi	d59d5c084d	Add implicit state file support Read implicit package list from /home/rick/.config/declpac or ~/.config/declpac	2026-05-03 14:30:16 +02:00
AI BotandRiyyi	c4746697b5	Remove merge package, move Merge to input	2026-05-03 14:30:16 +02:00
AI BotandRiyyi	5ad29767c9	Add safety check for package list validation	2026-05-03 14:30:16 +02:00
AI BotandRiyyi	38d26fd2d8	Add Go line length guidelines Adds 120/100/80 character guidelines to AGENTS.md	2026-05-03 12:17:12 +02:00
AI BotandRiyyi	399a7157e2	Add tilde path expansion for state files	2026-05-03 11:48:05 +02:00
AI BotandRiyyi	578eb16ab2	Add Go file structure conventions to AGENTS.md	2026-05-03 11:27:30 +02:00
AI BotandRiyyi	584f4fbdd9	Skip debug packages when finding built AUR package The findPKGFile function now takes pkgName as parameter to skip debug packages (*-debug.pkg.tar.zst) when locating built packages.	2026-05-03 11:13:06 +02:00
Riyyi	39b8d9ac4b	Add fmt command to makefile	2026-05-03 10:22:30 +02:00
AI BotandRiyyi	d36bba6925	Add centralized command logging function Refactors command execution to use a new log.Command helper that handles both logging and cmd creation, reducing duplication in sync.go	2026-05-03 10:05:10 +02:00
AI BotandRiyyi	b1a376dbbe	Add build, install and uninstall targets to Makefile	2026-04-24 21:14:03 +02:00
Riyyi	8a074e02b0	Update README.md	2026-04-19 11:20:08 +02:00
AI BotandRiyyi	fdd9ecb3a5	Handle pacman -Qdtq exit code 1 as non-error pacman -Qdtq exits with code 1 when there are no orphans, which is not an error condition. Handle this gracefully by returning nil instead of an error.	2026-04-19 11:08:32 +02:00
AI BotandRiyyi	c90d2e8916	Add verbose flag for debug output control Introduces log.Debug() function that respects a Verbose config flag, replacing direct [debug] fmt.Fprintf calls throughout the codebase. This allows debug logging to be toggled via -v/--verbose CLI flag.	2026-04-19 11:06:52 +02:00
Riyyi	1dffd70db2	Skip interactive prompt when removing orphans	2026-04-19 10:21:57 +02:00
AI BotandRiyyi	5ebb958bf1	Add command logging and skip already installed AUR packages	2026-04-19 10:15:00 +02:00
Riyyi	c7bed95107	Skip confirmation when installing packages	2026-04-18 20:35:18 +02:00
AI BotandRiyyi	a934dfa1f0	Update make-commit skill with message format rules	2026-04-18 18:50:25 +02:00
AI BotandRiyyi	e64382c1bd	Fix issues with dry-run package reporting - Filter orphans to only those not in requested packages - Fix Removed count to reflect only actual removals	2026-04-18 18:30:45 +02:00
AI BotandRiyyi	83de6acc74	Refactor fetch and pacman packages into subpackages Split fetch into alpm and aur subpackages for better organization. Rename state to log. Split pacman into read and sync subpackages. Remove validation in favor of read.DBFreshness.	2026-04-18 18:18:23 +02:00
Riyyi	88ff093365	Extract PacmanState constant	2026-04-18 16:16:13 +02:00
Riyyi	c2a7b9ab9c	Improve make-commit skill commit message formatting - Fix typo 'thed' to 'the' - Add 72-character title convention - Change --stat flag formatting to be more standard	2026-04-18 15:39:43 +02:00
AI BotandRiyyi	86c6d078d6	Output actual commands run instead of generic progress messages	2026-04-18 15:35:22 +02:00
AI BotandRiyyi	bd1108a93f	Dont use CombinedOutput() to capture error separately	2026-04-18 15:07:56 +02:00
AI BotandRiyyi	82aeceacac	Fixup: correct log path in add-operation-logging, fix pacman -Rns flag in declpac-cli-tool, update pkg path in fix-sync-dbs-notloaded	2026-04-18 14:27:47 +02:00
AI BotandRiyyi	86c1abaad4	Add opsx-fixup command for diverging change specs	2026-04-18 14:07:47 +02:00
AI BotandRiyyi	2b0cb39746	Update operation logging spec to use single timestamp per tool call	2026-04-18 13:44:48 +02:00
Riyyi	fc18e27c25	Log timestamp once per tool invocation	2026-04-18 13:37:50 +02:00
AI BotandRiyyi	8348cc21df	Suppress command output from stdout, only log to file	2026-04-17 23:34:53 +02:00
AI BotandRiyyi	01338cb671	Archive experimental OpenSpec changes	2026-04-17 19:35:25 +02:00
AI BotandRiyyi	b4b12b39b6	Openspec fixups	2026-04-17 19:26:06 +02:00
AI BotandRiyyi	720be92d82	Fix MarkAllAsDeps to retrieve all packages first	2026-04-17 19:06:03 +02:00
AI BotandRiyyi	4143a23c91	Implement package resolve logic fixes	2026-04-17 18:24:14 +02:00
AI BotandRiyyi	536a8d5ccb	Add package fetching logic fix proposal	2026-04-17 18:14:21 +02:00
AI BotandRiyyi	11a5e57516	Fix AUR package installation root privileges	2026-04-16 22:55:41 +02:00
AI BotandRiyyi	cffccf2390	Add Makefile and fix pacman.go	2026-04-16 22:24:36 +02:00
Riyyi	6fd4b64d92	Reorder main calls	2026-04-16 21:35:04 +02:00
AI BotandRiyyi	e74c38cb3f	Add input handling improvements	2026-04-16 21:31:05 +02:00
AI BotandRiyyi	192b41e18b	Rewrite README with accurate docs	2026-04-15 22:51:30 +02:00
Riyyi	1c74373d6b	Remove --yes flag	2026-04-15 22:46:11 +02:00
Riyyi	5e9b2521bd	Do not gitignore main.go file	2026-04-15 22:44:44 +02:00
AI BotandRiyyi	eb6bb8fb76	Add state tracking and pacman package enhancements	2026-04-15 22:40:02 +02:00
AI BotandRiyyi	0b834214cd	Add OpenSpec change for operation logging	2026-04-15 22:40:02 +02:00
Riyyi	5031fdc1f8	Improve make-commit skill documentation	2026-04-15 20:51:49 +02:00
AI BotandRiyyi	0fa0988666	Fix AUR package detection for installed packages	2026-04-15 19:57:34 +02:00
AI BotandRiyyi	2bead6af27	Refactor pkg into modular packages	2026-04-14 22:37:48 +02:00
AI BotandRiyyi	9aeedb39b8	Add OpenSpec change for pkg modularization refactor	2026-04-14 22:23:12 +02:00
AI BotandRiyyi	076bebbedf	Register sync DBs manually to fix dyalpm returning empty list The dyalpm library's SyncDBs() returns an empty slice, causing packages from official repos (extra, core, multilib) to not be found. This fix manually registers each repo after getting an empty result.	2026-04-14 22:05:42 +02:00
AI BotandRiyyi	836d8600c6	Add fix for sync DBs not loaded	2026-04-14 21:59:08 +02:00
AI BotandRiyyi	be9c9c6df1	Integrate dyalpm for local/sync package queries	2026-04-14 21:46:02 +02:00
AI BotandRiyyi	2a90c0cd11	Add batch pacman checks and package resolution specs	2026-04-14 19:57:29 +02:00
AI BotandRiyyi	521b862919	Add dry-run flag and implement AUR support	2026-04-13 21:42:11 +02:00
Riyyi	bd789ab18d	Update .gitignore and add LICENSE file	2026-04-13 19:31:19 +02:00
AI BotandRiyyi	d296e00fd6	Update README with usage documentation	2026-04-13 19:29:49 +02:00
AI BotandRiyyi	e165558262	Add initial declpac CLI tool implementation	2026-04-13 19:27:40 +02:00