next round of refactoring

src/cleanup.xq

@@ -0,0 +1,20 @@
+xquery version "3.1";
+
+declare namespace sm="http://exist-db.org/xquery/securitymanager";
+
+(: TODO: $target is not set in cleanup phase :)
+declare variable $configuration-collection := "/db/apps/tuttle/data/";
+declare variable $backup-collection := "/db/tuttle-backup/"; 
+declare variable $configuration-filename := "tuttle.xml";
+
+(: backup tuttle configuration :)
+if (not(xmldb:collection-available($backup-collection)))
+then ((: move/copy to collection :)
+    util:log("info", "Creating configuration backup collection"),
+    xmldb:create-collection("/db", "tuttle-backup"),
+    sm:chmod(xs:anyURI($backup-collection), "rwxr-x---")
+)
+else ()
+,
+util:log("info", "Backing up configuration"),
+xmldb:move($configuration-collection, $backup-collection, $configuration-filename)

src/data/tuttle.xml → src/data/tuttle-example-config.xml

@@ -1,30 +1,57 @@
 <tuttle>
   <repos>
     <collection name="tuttle-sample-data">
+        <!-- optional: make _one_ repository the default
+            for endpoints without {collection}
+        -->
         <default>true</default>
+
+        <!-- which sercive to connect to -->
         <type>github</type>
         <baseurl>https://api.github.com/</baseurl>
+
+        <!-- necessary to provide for GitHub -->
         <owner>eeditiones</owner>
         <repo>tuttle-sample-data</repo>
-        <token>XXX</token>
+
+        <!-- branch to pull from -->
         <ref>next</ref>
+
+        <!-- authenticate against remote service,
+            can also be read from environment variables -->
+        <token>XXX</token>
+
+        <!-- only necessary if you need the service to call tuttle -->
         <hookuser>admin</hookuser>
         <hookpasswd></hookpasswd>
     </collection>
 
    <collection name="tuttle-sample-gitlab">
+        <!-- which sercive to connect to -->
         <type>gitlab</type>
         <baseurl>https://gitlab.com/api/v4/</baseurl>
+
+        <!-- this is not needed for Gitlab but can be added for human consumption -->
         <owner>line-o</owner>
         <repo>tuttle-sample-data</repo>
+
+        <!-- necessary to provide for Gitlab -->
         <project-id>50872175</project-id>
-        <token>XXX</token>
+
+        <!-- branch to pull from -->
         <ref>main</ref>
+
+        <!-- authenticate against remote service,
+            can also be read from environment variables -->
+        <token>XXX</token>
+
+        <!-- only necessary if you need the service to call tuttle -->
         <hookuser>admin</hookuser>
         <hookpasswd></hookpasswd>
     </collection>
   </repos>
-
+
+  <!-- these files will not be extracted from archives and left untouched when cleaning up -->
   <blacklist>
       <file>existdb.json</file>
       <file>build.xml</file>
@@ -35,8 +62,9 @@
       <file>build.properties.xml</file>
   </blacklist>
 
-
+  <!-- prefix, suffix, lock and apikeys can usually be left as-is -->
   <config prefix="/db/apps/" suffix="-stage" lock="git-lock.xml" apikeys="/db/system/auth/tuttle-token.xml">
+    <!-- the permissions the deployed data gets assigned -->
     <sm user="nobody" group="nogroup" mode="rw-r--r--"/>
   </config>
 </tuttle>

src/finish.xq

@@ -0,0 +1,32 @@
+xquery version "3.1";
+
+declare namespace sm="http://exist-db.org/xquery/securitymanager";
+
+(: the target collection into which the app is deployed :)
+declare variable $target external;
+
+declare variable $configuration-collection := $target || "/data/";
+declare variable $backup-collection := "/db/tuttle-backup/"; 
+declare variable $configuration-filename := "tuttle.xml";
+
+(: look for backed up tuttle configuration :)
+if (doc-available($backup-collection || $configuration-filename))
+then ((: move/copy to collection :)
+    util:log("info", "Restoring tuttle configuration from backup."),
+    xmldb:move($backup-collection, $configuration-collection, $configuration-filename),
+    xmldb:remove($backup-collection)
+)
+else ((: copy example configuration when no backup was found :)
+    util:log("info", "No previous tuttle configuration found."),
+    xmldb:copy-resource(
+        $configuration-collection, "tuttle-example-config.xml",
+        $configuration-collection, $configuration-filename
+    )
+)
+,
+(: tighten security for configuration file :)
+sm:chmod(xs:anyURI($configuration-collection || $configuration-filename), "rw-r-----")
+,
+(: set gid for API :)
+sm:chmod(xs:anyURI($target || "/modules/api.xql"), "rwxr-sr-x")
+

src/repo.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<meta 
-  xmlns="http://exist-db.org/xquery/repo">
+<meta xmlns="http://exist-db.org/xquery/repo">
   <description>a Git Web API integration for eXist-db</description>
   <author>TEI Publisher Project Team</author>
   <website>https://github.com/eeditiones/tuttle</website>
@@ -9,5 +8,6 @@
   <copyright>true</copyright>
   <type>application</type>
   <target>tuttle</target>
-  <finish>post-install.xql</finish>
+  <finish>finish.xq</finish>
+  <cleanup>cleanup.xq</cleanup>
 </meta>